mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-07-02 05:38:12 +00:00
feat: adopt directory-based docs versioning with Edge channel
Switch docs.crewai.com from navigation-only versioning (every version selector entry rendered the same docs/<lang>/* source files) to Mintlify's directory-based versioning so each version selector entry renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/* that always reflects main HEAD for unreleased work, eliminating pre-release leakage onto frozen release labels. External links to canonical /<lang>/* URLs are preserved via wildcard redirects that always land on the current default version. Layout: - docs/edge/<lang>/* rolling source (you edit here) - docs/edge/enterprise-api.*.yaml - docs/v<X.Y.Z>/<lang>/* frozen, immutable snapshots - docs/v<X.Y.Z>/enterprise-api.*.yaml - docs/images/ shared, append-only - docs/docs.json nav + redirects URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links working, and every freeze rewrites them (plus all per-section/per-page redirects) so destinations always resolve to the current default without depending on a second redirect hop. Release flow integration (devtools release): - New module crewai_devtools.docs_versioning.freeze() materialises docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the snapshot, inserts the version into every language block in docs.json, and refreshes all redirect destinations. - _update_docs_and_create_pr() in cli.py now calls that freeze during Phase 2 of devtools release. Edge changelogs are updated first (so the snapshot freeze picks them up), then the snapshot is staged alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z> — the title prefix the new CI guard reads. - The PR still gates tag, GitHub release, PyPI publish, and the enterprise release as before; no new PRs are added. - Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride Edge — and the docs PR title omits the [docs-freeze] prefix. - docs_check (AI-generated docs scaffolding) writes to docs/edge/<lang>/* so newly-generated unreleased docs land in Edge and never accidentally touch a frozen snapshot. Migration scripts (one-shot): - scripts/docs/freeze_historical_versions.py reconstructs all 16 historical snapshots (v1.10.0 .. v1.14.7) from git tags via git archive | tar, rewriting openapi: MDX refs so each snapshot reads its own enterprise-api YAML rather than the live one. - scripts/docs/prefix_version_paths.py one-shot-migrates docs.json: rewrites every page path in 16 versioned blocks to point under docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags v1.14.7 as Latest (default), prunes pages whose target file doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before v1.12.0), and writes the wildcard + per-section redirects. - scripts/docs/freeze_current_edge.py is now a thin CLI wrapper around docs_versioning.freeze for manual one-off freezes (e.g. retroactively snapshotting a forgotten release). CI guards (.github/workflows/docs-snapshots.yml): - Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose title contains [docs-freeze] (i.e. release-cut PRs generated by devtools release or the manual wrapper) may modify them. - Images under docs/images/ are append-only since snapshots share a single image directory. Deleting or renaming an image breaks every historical snapshot that still references it. Restored docs/images/crewai-otel-export.png from PR #3673; it was deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference it. Restoring instead of editing the snapshots preserves historical rendering fidelity and validates the new append-only rule retroactively. Tests: - lib/devtools/tests/test_docs_versioning.py covers the freeze: file copy, openapi rewrite, version insertion, default demotion, redirect upserts, per-section redirect rewriting, idempotency, and invalid inputs. Verified locally with mintlify broken-links: 0 broken links across the full site (Edge + 16 frozen versions, 4 locales). AGENTS.md (repo root) is the contributor guide for the new model; RELEASING.md is the release-cut runbook; README's Contribution section links to both. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Lucas Gomide
61
docs/edge/ko/guides/coding-tools/agents-md.mdx
Normal file
61
docs/edge/ko/guides/coding-tools/agents-md.mdx
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: 코딩 도구
|
||||
description: AGENTS.md를 사용하여 CrewAI 프로젝트 전반에서 코딩 에이전트와 IDE를 안내합니다.
|
||||
icon: terminal
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## AGENTS.md를 사용하는 이유
|
||||
|
||||
`AGENTS.md`는 가벼운 저장소 로컬 지침 파일로, 코딩 에이전트에게 일관되고 프로젝트별 안내를 제공합니다. 프로젝트 루트에 배치하고 어시스턴트가 작업하는 방식(컨벤션, 명령어, 아키텍처 노트, 가드레일)에 대한 신뢰할 수 있는 소스로 활용하세요.
|
||||
|
||||
## CLI로 프로젝트 생성
|
||||
|
||||
CrewAI CLI를 사용하여 프로젝트를 스캐폴딩하면, `AGENTS.md`가 루트에 자동으로 추가됩니다.
|
||||
|
||||
```bash
|
||||
# Crew
|
||||
crewai create crew my_crew
|
||||
|
||||
# Flow
|
||||
crewai create flow my_flow
|
||||
|
||||
# Tool repository
|
||||
crewai tool create my_tool
|
||||
```
|
||||
|
||||
## 도구 설정: 어시스턴트에 AGENTS.md 연결
|
||||
|
||||
### Codex
|
||||
|
||||
Codex는 저장소에 배치된 `AGENTS.md` 파일로 안내할 수 있습니다. 컨벤션, 명령어, 워크플로우 기대치 등 지속적인 프로젝트 컨텍스트를 제공하는 데 사용하세요.
|
||||
|
||||
### Claude Code
|
||||
|
||||
Claude Code는 프로젝트 메모리를 `CLAUDE.md`에 저장합니다. `/init`으로 부트스트랩하고 `/memory`로 편집할 수 있습니다. Claude Code는 `CLAUDE.md` 내에서 임포트도 지원하므로, `@AGENTS.md`와 같은 한 줄을 추가하여 공유 지침을 중복 없이 가져올 수 있습니다.
|
||||
|
||||
간단하게 다음과 같이 사용할 수 있습니다:
|
||||
|
||||
```bash
|
||||
mv AGENTS.md CLAUDE.md
|
||||
```
|
||||
|
||||
### Gemini CLI와 Google Antigravity
|
||||
|
||||
Gemini CLI와 Antigravity는 저장소 루트 및 상위 디렉토리에서 프로젝트 컨텍스트 파일(기본값: `GEMINI.md`)을 로드합니다. Gemini CLI 설정에서 `context.fileName`을 설정하여 `AGENTS.md`를 대신(또는 추가로) 읽도록 구성할 수 있습니다. 예를 들어, `AGENTS.md`만 설정하거나 각 도구의 형식을 유지하고 싶다면 `AGENTS.md`와 `GEMINI.md`를 모두 포함할 수 있습니다.
|
||||
|
||||
간단하게 다음과 같이 사용할 수 있습니다:
|
||||
|
||||
```bash
|
||||
mv AGENTS.md GEMINI.md
|
||||
```
|
||||
|
||||
### Cursor
|
||||
|
||||
Cursor는 `AGENTS.md`를 프로젝트 지침 파일로 지원합니다. 프로젝트 루트에 배치하여 Cursor의 코딩 어시스턴트에 안내를 제공하세요.
|
||||
|
||||
### Windsurf
|
||||
|
||||
Claude Code는 Windsurf와의 공식 통합을 제공합니다. Windsurf 내에서 Claude Code를 사용하는 경우, 위의 Claude Code 안내를 따르고 `CLAUDE.md`에서 `AGENTS.md`를 임포트하세요.
|
||||
|
||||
Windsurf의 네이티브 어시스턴트를 사용하는 경우, 프로젝트 규칙 또는 지침 기능(사용 가능한 경우)을 구성하여 `AGENTS.md`에서 읽거나 내용을 직접 붙여넣으세요.
|
||||
214
docs/edge/ko/guides/coding-tools/build-with-ai.mdx
Normal file
214
docs/edge/ko/guides/coding-tools/build-with-ai.mdx
Normal file
@@ -0,0 +1,214 @@
|
||||
---
|
||||
title: "AI와 함께 빌드하기"
|
||||
description: "CrewAI로 빌드·배포·확장하는 데 필요한 모든 것 — 스킬, 기계가 읽을 수 있는 문서, 배포, 엔터프라이즈 기능을 AI 코딩 에이전트용으로 정리했습니다."
|
||||
icon: robot
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# AI와 함께 빌드하기
|
||||
|
||||
CrewAI는 AI 네이티브입니다. 이 페이지는 Claude Code, Codex, Cursor, Gemini CLI 등 개발자가 crew와 flow를 배포하도록 돕는 코딩 에이전트가 CrewAI로 빌드할 때 필요한 내용을 한곳에 모았습니다.
|
||||
|
||||
### 지원 코딩 에이전트
|
||||
|
||||
<CardGroup cols={5}>
|
||||
<Card title="Claude Code" icon="message-bot" color="#D97706" />
|
||||
<Card title="Cursor" icon="arrow-pointer" color="#3B82F6" />
|
||||
<Card title="Codex" icon="terminal" color="#10B981" />
|
||||
<Card title="Windsurf" icon="wind" color="#06B6D4" />
|
||||
<Card title="Gemini CLI" icon="sparkles" color="#8B5CF6" />
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
이 페이지는 사람과 AI 어시스턴트 모두를 위해 작성되었습니다. 코딩 에이전트라면 CrewAI 맥락은 **Skills**부터, 전체 문서 접근은 **llms.txt**를 사용하세요.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## 1. Skills — 에이전트에게 CrewAI 가르치기
|
||||
|
||||
**Skills**는 코딩 에이전트에게 Flow 스캐폴딩, Crew 구성, 도구 사용, 프레임워크 관례 등 CrewAI에 대한 깊은 지식을 담은 지침 묶음입니다.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Claude Code (플러그인 마켓플레이스)">
|
||||
<img src="https://cdn.simpleicons.org/anthropic/D97706" alt="Anthropic" width="28" style={{display: "inline", verticalAlign: "middle", marginRight: "8px"}} />
|
||||
CrewAI 스킬은 **Claude Code 플러그인 마켓플레이스**에서 제공됩니다. AI 네이티브 기업들이 쓰는 것과 같은 배포 채널입니다.
|
||||
```shell
|
||||
/plugin marketplace add crewAIInc/skills
|
||||
/plugin install crewai-skills@crewai-plugins
|
||||
/reload-plugins
|
||||
```
|
||||
|
||||
CrewAI와 관련된 질문을 하면 다음 네 가지 스킬이 자동으로 활성화됩니다.
|
||||
|
||||
| 스킬 | 실행 시점 |
|
||||
|------|-------------|
|
||||
| `getting-started` | 새 프로젝트 스캐폴딩, `LLM.call()` / `Agent` / `Crew` / `Flow` 선택, `crew.jsonc` / `main.py` 연결 |
|
||||
| `design-agent` | 에이전트 구성 — 역할, 목표, 배경 이야기, 도구, LLM, 메모리, 가드레일 |
|
||||
| `design-task` | 태스크 설명, 의존성, 구조화된 출력(`output_pydantic`, `output_json`), 사람 검토 |
|
||||
| `ask-docs` | 최신 API 정보를 위해 [CrewAI 문서 MCP 서버](https://docs.crewai.com/mcp) 조회 |
|
||||
</Tab>
|
||||
<Tab title="npx (모든 에이전트)">
|
||||
Claude Code, Codex, Cursor, Gemini CLI 등 모든 코딩 에이전트에서 사용할 수 있습니다.
|
||||
```shell
|
||||
npx skills add crewaiinc/skills
|
||||
```
|
||||
[skills.sh 레지스트리](https://skills.sh/crewaiinc/skills)에서 가져옵니다.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Steps>
|
||||
<Step title="공식 스킬 팩 설치">
|
||||
위 방법 중 하나를 사용하세요 — Claude Code 플러그인 마켓플레이스 또는 `npx skills add`. 둘 다 공식 [crewAIInc/skills](https://github.com/crewAIInc/skills) 팩을 설치합니다.
|
||||
</Step>
|
||||
<Step title="에이전트가 즉시 CrewAI 전문성을 갖춤">
|
||||
스킬 팩이 에이전트에게 알려 주는 내용:
|
||||
- **Flow** — 상태ful 앱, 단계, crew 킥오프
|
||||
- **Crew 및 에이전트** — JSON-first 패턴(`crew.jsonc`, `agents/*.jsonc`), 역할, 태스크, 위임
|
||||
- **도구 및 통합** — 검색, API, MCP 서버, 일반적인 CrewAI 도구
|
||||
- **프로젝트 레이아웃** — CLI 스캐폴드와 저장소 관례
|
||||
- **최신 패턴** — 현재 CrewAI 문서와 모범 사례 반영
|
||||
</Step>
|
||||
<Step title="빌드 시작">
|
||||
매 세션마다 프레임워크를 다시 설명하지 않아도 에이전트가 CrewAI 프로젝트를 스캐폴딩하고 빌드할 수 있습니다.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Skills 개념" icon="bolt" href="/ko/concepts/skills">
|
||||
CrewAI 에이전트에서 스킬이 동작하는 방식 — 주입, 활성화, 패턴.
|
||||
</Card>
|
||||
<Card title="Skills 랜딩 페이지" icon="wand-magic-sparkles" href="/ko/skills">
|
||||
crewAIInc/skills 팩 개요와 포함 내용.
|
||||
</Card>
|
||||
<Card title="AGENTS.md 및 코딩 도구" icon="terminal" href="/ko/guides/coding-tools/agents-md">
|
||||
Claude Code, Codex, Cursor, Gemini CLI용 AGENTS.md 설정.
|
||||
</Card>
|
||||
<Card title="Skills 레지스트리 (skills.sh)" icon="globe" href="https://skills.sh/crewaiinc/skills">
|
||||
공식 목록 — 스킬, 설치 통계, 감사 정보.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
---
|
||||
|
||||
## 2. llms.txt — 기계가 읽을 수 있는 문서
|
||||
|
||||
CrewAI는 AI 어시스턴트가 전체 문서에 기계가 읽을 수 있는 형태로 바로 접근할 수 있도록 `llms.txt` 파일을 제공합니다.
|
||||
|
||||
```
|
||||
https://docs.crewai.com/llms.txt
|
||||
```
|
||||
|
||||
<Tabs>
|
||||
<Tab title="llms.txt란?">
|
||||
[`llms.txt`](https://llmstxt.org/)는 문서를 대규모 언어 모델이 소비하기 쉽게 만드는 새로운 표준입니다. HTML을 스크래핑하는 대신, 필요한 내용이 담긴 하나의 구조화된 텍스트 파일을 가져올 수 있습니다.
|
||||
|
||||
CrewAI의 `llms.txt`는 **이미 제공 중**이며, 에이전트가 바로 사용할 수 있습니다.
|
||||
</Tab>
|
||||
<Tab title="사용 방법">
|
||||
CrewAI 참고 문서가 필요할 때 코딩 에이전트에 URL을 알려 주세요.
|
||||
|
||||
```
|
||||
Fetch https://docs.crewai.com/llms.txt for CrewAI documentation.
|
||||
```
|
||||
|
||||
Claude Code, Cursor 등 많은 코딩 에이전트가 URL을 직접 가져올 수 있습니다. 파일에는 CrewAI 개념, API, 가이드를 아우르는 구조화된 문서가 포함되어 있습니다.
|
||||
</Tab>
|
||||
<Tab title="왜 중요한가">
|
||||
- **스크래핑 불필요** — 한 번의 요청으로 깔끔한 구조화 콘텐츠
|
||||
- **항상 최신** — docs.crewai.com에서 직접 제공
|
||||
- **LLM에 최적화** — 브라우저가 아니라 컨텍스트 윈도우에 맞게 포맷
|
||||
- **스킬과 상호 보완** — 스킬은 패턴을, llms.txt는 참조를 제공
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## 3. 엔터프라이즈에 배포
|
||||
|
||||
로컬 crew를 몇 분 안에 **CrewAI AMP**(Agent Management Platform) 프로덕션으로 가져가세요.
|
||||
|
||||
<Steps>
|
||||
<Step title="로컬에서 빌드">
|
||||
crew 또는 flow를 스캐폴딩하고 테스트합니다.
|
||||
```bash
|
||||
crewai create crew my_crew
|
||||
cd my_crew
|
||||
crewai run
|
||||
```
|
||||
</Step>
|
||||
<Step title="배포 준비">
|
||||
프로젝트 구조가 준비되었는지 확인합니다.
|
||||
```bash
|
||||
crewai deploy --prepare
|
||||
```
|
||||
구조와 요구 사항은 [준비 가이드](/ko/enterprise/guides/prepare-for-deployment)를 참고하세요.
|
||||
</Step>
|
||||
<Step title="AMP에 배포">
|
||||
CrewAI AMP 플랫폼으로 푸시합니다.
|
||||
```bash
|
||||
crewai deploy
|
||||
```
|
||||
[GitHub 연동](/ko/enterprise/guides/deploy-to-amp) 또는 [Crew Studio](/ko/enterprise/guides/enable-crew-studio)로도 배포할 수 있습니다.
|
||||
</Step>
|
||||
<Step title="API로 접근">
|
||||
배포된 crew는 REST API 엔드포인트를 받습니다. 모든 애플리케이션에 통합할 수 있습니다.
|
||||
```bash
|
||||
curl -X POST https://app.crewai.com/api/v1/crews/<crew-id>/kickoff \
|
||||
-H "Authorization: Bearer $CREWAI_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"inputs": {"topic": "AI agents"}}'
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="AMP에 배포" icon="rocket" href="/ko/enterprise/guides/deploy-to-amp">
|
||||
전체 배포 가이드 — CLI, GitHub, Crew Studio 방법.
|
||||
</Card>
|
||||
<Card title="AMP 소개" icon="globe" href="/ko/enterprise/introduction">
|
||||
플랫폼 개요 — 프로덕션 crew에 AMP가 제공하는 것.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
---
|
||||
|
||||
## 4. 엔터프라이즈 기능
|
||||
|
||||
CrewAI AMP는 프로덕션 팀을 위해 만들어졌습니다. 배포 외에 제공되는 것은 다음과 같습니다.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="관측 가능성" icon="chart-line">
|
||||
모든 crew 실행에 대한 상세 실행 추적, 로그, 성능 지표. 에이전트 결정, 도구 호출, 태스크 완료를 실시간으로 모니터링합니다.
|
||||
</Card>
|
||||
<Card title="Crew Studio" icon="paintbrush">
|
||||
시각적으로 crew를 만들고, 맞춤 설정하고, 배포하는 노코드/로코드 인터페이스 — 코드로 보내거나 바로 배포할 수 있습니다.
|
||||
</Card>
|
||||
<Card title="웹훅 스트리밍" icon="webhook">
|
||||
crew 실행에서 실시간 이벤트를 시스템으로 스트리밍합니다. Slack, Zapier 등 웹훅 소비자와 연동할 수 있습니다.
|
||||
</Card>
|
||||
<Card title="팀 관리" icon="users">
|
||||
SSO, RBAC, 조직 단위 제어. 팀 전체에서 crew 생성·배포·접근 권한을 관리합니다.
|
||||
</Card>
|
||||
<Card title="도구 저장소" icon="toolbox">
|
||||
조직 전체에 맞춤 도구를 게시하고 공유합니다. 레지스트리에서 커뮤니티 도구를 설치합니다.
|
||||
</Card>
|
||||
<Card title="Factory(셀프 호스팅)" icon="server">
|
||||
자체 인프라에서 CrewAI AMP를 실행합니다. 데이터 상주와 규정 준수 제어와 함께 플랫폼 전체 기능을 사용할 수 있습니다.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="AMP는 누구를 위한 것인가요?">
|
||||
AI 에이전트 워크플로를 프로토타입에서 프로덕션으로 옮겨야 하는 팀을 위한 제품입니다. 관측 가능성, 접근 제어, 확장 가능한 인프라를 제공합니다. 스타트업이든 대기업이든 운영 복잡도는 AMP가 맡고, 에이전트 구축에 집중할 수 있습니다.
|
||||
</Accordion>
|
||||
<Accordion title="배포 옵션은 무엇이 있나요?">
|
||||
- **클라우드 (app.crewai.com)** — CrewAI가 관리, 프로덕션까지 가장 빠른 경로
|
||||
- **Factory(셀프 호스팅)** — 데이터 통제를 위해 자체 인프라에서 실행
|
||||
- **하이브리드** — 민감도에 따라 클라우드와 셀프 호스팅을 혼합
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Card title="CrewAI AMP 살펴보기 →" icon="arrow-right" href="https://app.crewai.com">
|
||||
가입하고 첫 crew를 프로덕션에 배포해 보세요.
|
||||
</Card>
|
||||
Reference in New Issue
Block a user