214 lines
12 KiB
Markdown
214 lines
12 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 # 진입 파일 목록의 단일 기준
|
|
│ ├── ai-ignore.sh # AI ignore / permission 기본 설정
|
|
│ ├── 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
|
|
└── skills/
|
|
├── common/ # 공통 스킬 (수정 금지)
|
|
│ ├── router.md # 공통 스킬 라우터
|
|
│ ├── _templates/
|
|
│ │ ├── skill-template.md
|
|
│ │ ├── roadmap-template.md
|
|
│ │ ├── roadmap-current-template.md
|
|
│ │ ├── roadmap-milestone-template.md
|
|
│ │ ├── roadmap-sdd-template.md
|
|
│ │ ├── roadmap-sdd-user-review-template.md
|
|
│ │ └── roadmap-position-report-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 # 로드맵 변경 제안과 file-based fallback 갱신
|
|
│ ├── roadmap-sdd/SKILL.md # 큰 Milestone의 SDD gate와 사용자 리뷰 잠금
|
|
│ ├── analyze-roadmap-position/SKILL.md # 로드맵 현지점 확인
|
|
│ └── update-domain-rule/SKILL.md # 도메인 규칙 수정
|
|
└── project/ # 프로젝트 스킬 (수정 가능)
|
|
└── <skill-name>/SKILL.md
|
|
agent-roadmap/ # 프로젝트 로드맵 (create-roadmap 실행 시 생성)
|
|
├── ROADMAP.md
|
|
├── current.md # local, git ignored
|
|
├── phase/<phase-slug>/PHASE.md
|
|
├── phase/<phase-slug>/milestones/<milestone-slug>.md
|
|
├── sdd/<phase-slug>/<milestone-slug>/SDD.md
|
|
├── sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md
|
|
├── archive/phase/<phase-slug>/...
|
|
└── archive/sdd/<phase-slug>/<milestone-slug>/...
|
|
```
|
|
|
|
로드맵 문서는 사람이 함께 검토하고 수정하는 협업 문서이므로 전체 구성과 설명 문장을 기본 한국어로 작성합니다. Goal, Phase, Milestone, API 같은 일반 개발 용어와 파일명, 경로, slug 같은 식별자는 영어 또는 숫자를 유지할 수 있습니다.
|
|
|
|
Phase와 Milestone에는 순번을 강제하지 않습니다. 진행 순서는 `ROADMAP.md`에 적힌 위에서 아래 순서로 봅니다. 새 작업을 추가할 때는 사용자가 지정한 위치를 우선하고, 단위 지정이 없으면 작업 성격을 보고 새 Milestone, 기존 Milestone의 태스크, 기존 태스크의 하위 작업 중 적절한 단위로 배치합니다.
|
|
|
|
로드맵 문서는 `agent-ops/skills/common/_templates/roadmap-template.md`, `roadmap-current-template.md`, `roadmap-milestone-template.md` 형식을 기준으로 작성합니다. 로컬 `agent-roadmap/current.md`는 `roadmap-current-template.md` 형식으로 만들며 git 추적 대상이 아닙니다. 해야 할 작업은 Milestone 문서의 `기능` 체크리스트로 두고, 완료 여부를 검증하는 조건은 필요한 Task 안의 `검증:` 문구로 둡니다.
|
|
|
|
로드맵 스킬은 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신을 담당합니다. Core/MCP가 있는 프로젝트에서는 상태 전환, archive 이동, 외부 의존 lock 동기화, 완료 이벤트 반영 같은 action을 Core/MCP 또는 런타임이 처리합니다.
|
|
|
|
Milestone의 `구현 잠금`은 승인 절차가 아니라 사용자 결정이 필요한지 표시하는 상태 기록입니다. 제품 방향, 범위, 우선순위, 설계 경계처럼 사용자 결정이 필요한 항목이 있으면 `잠금`으로 두고 `결정 필요` 체크리스트에 질문을 적습니다. 작업에 필요한 결정이 이미 정해져 에이전트가 실행만 하면 되는 Milestone은 `해제`로 둡니다.
|
|
|
|
큰 Milestone은 `구현 잠금` 안에 SDD gate를 가질 수 있습니다. SDD는 사용자가 별도로 운용하는 설계 문서가 아니라, agent가 짧은 로드맵 요청을 source of truth, 상태 전이, interface, acceptance scenario, evidence map으로 확장해야 할 때 쓰는 하위 문서입니다. 사용자 결정이 필요한 항목은 채팅 질문으로 흩어지지 않고 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md`에 모이며, 해당 리뷰가 해결되고 SDD 잠금이 해제되어야 Milestone 구현 잠금도 해제 후보가 됩니다.
|
|
|
|
SDD는 cross-repo 계약, 외부 provider 쓰기, 상태 머신, idempotency/retry/identity map, API/proto/config/env/schema 변경, field smoke, 사용자 승인 gate에 영향을 주는 작업에만 강제합니다. 작은 리팩터링, 문서 정리, 테스트 보강, 작은 UI 보강에는 기존 roadmap + agent-task 흐름을 유지합니다.
|
|
|
|
현재 작업 지점 답변은 `agent-ops/skills/common/_templates/roadmap-position-report-template.md` 형식을 기준으로 작성합니다.
|
|
|
|
완료된 task 산출물은 `agent-task/archive/YYYY/MM/` 아래로, 완료 또는 폐기되어 현재 작업 후보에서 제외할 과거 Phase/Milestone은 `agent-roadmap/archive/phase/<phase-slug>/`로 이동합니다. active plan/review는 후속 작업에 필요한 archive 근거를 자체 섹션으로 복사해야 하며, 아카이브 문서는 사용자가 과거 기록 확인, 복원, 비교를 요청했거나 active plan/review가 특정 archive evidence 경로를 명시한 경우에만 해당 파일을 좁게 읽습니다.
|
|
|
|
---
|
|
|
|
## 적용 방법
|
|
|
|
### 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` (프로젝트 스킬) | 자유롭게 수정 |
|