# 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/
│       └── M01-<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-roadmap/SKILL.md       # Goal/Phase/Milestone 로드맵 생성
    │   ├── update-roadmap/SKILL.md       # 로드맵 상태/마일스톤 갱신
    │   ├── create-readme/SKILL.md        # README 생성
    │   ├── update-readme/SKILL.md        # README 정리/갱신
    │   └── update-domain-rule/SKILL.md   # 도메인 규칙 수정
    └── project/                          # 프로젝트 스킬 (수정 가능)
        └── <skill-name>/SKILL.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` (프로젝트 스킬) | 자유롭게 수정 |