188 lines
8.3 KiB
Markdown
188 lines
8.3 KiB
Markdown
# Agent Context Framework 적용 가이드
|
|
|
|
이 문서는 `agent-ops/` 폴더를 프로젝트에 복사한 뒤 참고하는 가이드입니다.
|
|
|
|
---
|
|
|
|
## 간단 적용
|
|
|
|
**1. `agent-ops/` 폴더를 타겟 프로젝트 루트에 복사합니다.**
|
|
|
|
**2. 에이전트에게 아래와 같이 정확한 경로를 지정해 초기화를 요청합니다.**
|
|
|
|
> 초기 세팅 전에는 진입 파일(CLAUDE.md 등)이 없어 라우팅이 불가능하므로, 반드시 스킬 파일 경로를 직접 안내해야 합니다.
|
|
|
|
```
|
|
agent-ops/skills/common/init-agent-ops/SKILL.md 를 읽고 실행해줘.
|
|
```
|
|
|
|
`init-agent-ops` 스킬이 프로젝트를 분석하고 다음을 자동 생성합니다.
|
|
- 진입 파일 (CLAUDE.md 등)
|
|
- `rules/project/rules.md`
|
|
- `rules/project/domain/<name>/rules.md`
|
|
|
|
---
|
|
|
|
## 구성
|
|
|
|
```
|
|
agent-ops/
|
|
├── GUIDE.md # 이 파일 (적용 가이드)
|
|
├── .version # 프레임워크 버전 (타겟 프로젝트 버전 추적용)
|
|
├── bin/
|
|
│ ├── entry-files.sh # 진입 파일 목록의 단일 기준
|
|
│ ├── init-agent-ops.sh # 초기화 스크립트
|
|
│ ├── sync.sh # 동기화 스크립트
|
|
│ └── bump-version.sh # 버전 증가 스크립트
|
|
├── rules/
|
|
│ ├── common/ # 공통 규칙 (수정 금지)
|
|
│ │ ├── rules.md # 공통 규칙 (에이전트 진입 파일로 사용)
|
|
│ │ └── _templates/
|
|
│ │ └── domain-rule-template.md
|
|
│ ├── project/ # 프로젝트 규칙 (수정 가능)
|
|
│ │ ├── rules.md # 프로젝트 특화 규칙 (init-agent-ops가 생성)
|
|
│ │ └── domain/ # 도메인별 규칙
|
|
│ │ └── <domain-name>/rules.md
|
|
│ └── private/ # 개인 규칙 (git 제외, 선택)
|
|
│ └── rules.md
|
|
├── roadmap/ # 프로젝트 로드맵 (create-roadmap 실행 시 생성)
|
|
│ ├── ROADMAP.md
|
|
│ ├── current.md
|
|
│ └── milestones/
|
|
│ └── <milestone-slug>.md
|
|
└── skills/
|
|
├── common/ # 공통 스킬 (수정 금지)
|
|
│ ├── router.md # 공통 스킬 라우터
|
|
│ ├── _templates/
|
|
│ │ └── skill-template.md
|
|
│ ├── init-agent-ops/SKILL.md # scaffold 초기화
|
|
│ ├── sync-pull/SKILL.md # framework → 현재 프로젝트 동기화
|
|
│ ├── sync-push/SKILL.md # 현재 프로젝트/framework push 동기화
|
|
│ ├── commit-push/SKILL.md # 커밋 & 푸시
|
|
│ ├── create-domain-rule/SKILL.md # 도메인 규칙 생성
|
|
│ ├── create-skill/SKILL.md # 스킬 생성
|
|
│ ├── create-readme/SKILL.md # README 생성
|
|
│ ├── create-roadmap/SKILL.md # Goal/Phase/Milestone 로드맵 생성
|
|
│ ├── update-roadmap/SKILL.md # 로드맵 상태/마일스톤 갱신
|
|
│ ├── analyze-roadmap-position/SKILL.md # 현재 작업 지점/남은 작업 분석
|
|
│ └── update-domain-rule/SKILL.md # 도메인 규칙 수정
|
|
└── project/ # 프로젝트 스킬 (수정 가능)
|
|
└── <skill-name>/SKILL.md
|
|
```
|
|
|
|
로드맵 문서는 사람이 함께 검토하고 수정하는 협업 문서이므로 전체 구성과 설명 문장을 기본 한국어로 작성합니다. Goal, Phase, Milestone, API 같은 일반 개발 용어와 파일명, 경로, slug 같은 식별자는 영어 또는 숫자를 유지할 수 있습니다.
|
|
|
|
Phase와 Milestone에는 순번을 강제하지 않습니다. 진행 순서는 `ROADMAP.md`에 적힌 위에서 아래 순서로 봅니다.
|
|
|
|
---
|
|
|
|
## 적용 방법
|
|
|
|
### 1. 복사
|
|
|
|
이 레포의 `agent-ops/` 폴더를 타겟 프로젝트 루트에 복사합니다.
|
|
|
|
```
|
|
project-root/
|
|
├── agent-ops/ ← 복사
|
|
└── ...
|
|
```
|
|
|
|
### 2. 진입 파일 배치
|
|
|
|
`agent-ops/rules/common/rules.md`를 사용하는 에이전트에 맞는 파일명으로 프로젝트 루트에 복사합니다.
|
|
실제 생성/동기화 대상 목록은 `agent-ops/bin/entry-files.sh`의 `AGENT_OPS_ENTRY_FILES`를 단일 기준으로 사용합니다.
|
|
|
|
| 에이전트 | 파일명 |
|
|
|---------|--------|
|
|
| Gemini | `GEMINI.md` |
|
|
| Claude | `CLAUDE.md` |
|
|
| Kilo Code / OpenCode | `AGENTS.md` |
|
|
| Cursor | `.cursorrules` |
|
|
| Cline | `.clinerules` |
|
|
|
|
```
|
|
project-root/
|
|
├── CLAUDE.md ← rules/common/rules.md 복사
|
|
├── agent-ops/
|
|
└── ...
|
|
```
|
|
|
|
### 3. scaffold 스킬 실행
|
|
|
|
AI 에이전트에게 초기화를 요청합니다.
|
|
|
|
```
|
|
agent-ops 초기화해줘.
|
|
```
|
|
|
|
에이전트가 프로젝트 구조를 분석하고 다음을 자동 생성합니다:
|
|
- `rules/project/rules.md` — 프로젝트 특화 규칙 (응답 언어, 프로젝트 개요, 기술 스택)
|
|
- `rules/project/domain/<name>/rules.md` — 도메인별 규칙 초안
|
|
|
|
### 4. 개인 규칙 설정 (선택)
|
|
|
|
`agent-ops/rules/private/rules.md`를 생성하여 개인 선호 규칙을 정의할 수 있습니다.
|
|
|
|
- 응답 언어, 출력 스타일 등 개인 설정
|
|
- 팀 공통 규칙(`project/rules.md`)과 충돌하지 않는 범위에서 자유롭게 작성
|
|
- `.gitignore`에 `agent-ops/rules/private/`가 추가되어 있으므로 커밋되지 않습니다
|
|
|
|
### 6. 내용 확인 및 보완
|
|
|
|
스킬 실행 후 다음 항목을 확인합니다.
|
|
|
|
| 파일 | 확인할 내용 |
|
|
|------|------------|
|
|
| `rules/project/rules.md` | 응답 언어, 프로젝트 개요, 기술 스택, 특화 컨벤션, 도메인 매핑 테이블 |
|
|
| `rules/project/domain/*/rules.md` | 도메인별 경로, 구성 요소, 패턴, 경계 |
|
|
|
|
### 7. 개발 시작
|
|
|
|
구성이 완료되면 에이전트는 모든 작업 요청 시 자동으로 rules와 skills를 참조합니다.
|
|
|
|
---
|
|
|
|
## 파일 흐름
|
|
|
|
```
|
|
진입 파일 (CLAUDE.md 등) = rules/common/rules.md 내용
|
|
→ skills/common/router.md (공통 스킬 요청 시)
|
|
→ skills/common/<skill>/SKILL.md
|
|
→ rules/project/rules.md
|
|
→ skills/project/<skill>/SKILL.md 또는 rules/project/domain/<name>/rules.md
|
|
```
|
|
|
|
---
|
|
|
|
## 공통 파일 수정 보호
|
|
|
|
에이전트는 프로젝트 루트의 `.agent-ops-source` 마커 파일 유무로 공통 파일 수정 가능 여부를 판단합니다.
|
|
|
|
| 마커 | 의미 | 공통 파일 수정 |
|
|
|------|------|--------------|
|
|
| `.agent-ops-source` 있음 | 공통 관리 레포 | 허용 |
|
|
| `.agent-ops-source` 없음 | 타겟 프로젝트 | **금지** |
|
|
|
|
**중요**: `agent-ops/` 폴더를 타겟 프로젝트에 복사할 때 `.agent-ops-source` 파일은 복사하지 마세요. 이 파일은 `agent-ops/` 밖(프로젝트 루트)에 있으므로 `agent-ops/` 폴더만 복사하면 자연스럽게 제외됩니다.
|
|
|
|
수정이 필요한 경우 공통 관리 레포에 반영하고, 해당 변경 내용을 각 프로젝트에 수동으로 싱크합니다.
|
|
|
|
각 공통 파일의 frontmatter에는 개별 `version`이 명시되어 있습니다.
|
|
|
|
프레임워크 전체 버전은 `agent-ops/.version` 파일에 기록됩니다. `init-agent-ops` 실행 시 이 파일이 타겟 프로젝트에 함께 복사되므로, 타겟 프로젝트의 `agent-ops/.version`을 확인하면 어느 시점의 프레임워크를 기반으로 하는지 파악할 수 있습니다.
|
|
|
|
---
|
|
|
|
## 수정 가능 / 불가능 파일 구분
|
|
|
|
| 구분 | 파일 | 수정 |
|
|
|------|------|------|
|
|
| 공통 (수정 금지) | `.version` | 공통 레포에서만 수정 |
|
|
| 공통 (수정 금지) | `rules/common/rules.md` | 공통 레포에서만 수정 |
|
|
| 공통 (수정 금지) | `rules/common/_templates/*.md` | 공통 레포에서만 수정 |
|
|
| 공통 (수정 금지) | `skills/common/*/SKILL.md` (공통 스킬) | 공통 레포에서만 수정 |
|
|
| 공통 (수정 금지) | `skills/common/_templates/*.md` | 공통 레포에서만 수정 |
|
|
| 프로젝트 (수정 가능) | `rules/project/rules.md` | 프로젝트에 맞게 수정 |
|
|
| 프로젝트 (수정 가능) | `rules/project/domain/*/rules.md` | 프로젝트에 맞게 수정 |
|
|
| 프로젝트 (수정 가능) | `skills/project/*/SKILL.md` (프로젝트 스킬) | 자유롭게 수정 |
|