168 lines
6.7 KiB
Markdown
168 lines
6.7 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 # 프레임워크 버전 (타겟 프로젝트 버전 추적용)
|
|
├── 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
|
|
│ ├── init-agent-ops/SKILL.md # scaffold 초기화
|
|
│ ├── sync-agent-ops/SKILL.md # 진입 파일 재적용
|
|
│ ├── commit-push/SKILL.md # 커밋 & 푸시
|
|
│ ├── create-domain-rule/SKILL.md # 도메인 규칙 생성
|
|
│ ├── create-skill/SKILL.md # 스킬 생성
|
|
│ └── version-bump/SKILL.md # 버전 업데이트
|
|
└── project/ # 프로젝트 스킬 (수정 가능)
|
|
└── <skill-name>/SKILL.md
|
|
```
|
|
|
|
---
|
|
|
|
## 적용 방법
|
|
|
|
### 1. 복사
|
|
|
|
이 레포의 `agent-ops/` 폴더를 타겟 프로젝트 루트에 복사합니다.
|
|
|
|
```
|
|
project-root/
|
|
├── agent-ops/ ← 복사
|
|
└── ...
|
|
```
|
|
|
|
### 2. 진입 파일 배치
|
|
|
|
`agent-ops/rules/common/rules.md`를 사용하는 에이전트에 맞는 파일명으로 프로젝트 루트에 복사합니다.
|
|
|
|
| 에이전트 | 파일명 |
|
|
|---------|--------|
|
|
| Claude | `CLAUDE.md` |
|
|
| Gemini | `GEMINI.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` (프로젝트 스킬) | 자유롭게 수정 |
|