# Agent Context Framework

AI 에이전트가 매 작업마다 필요한 컨텍스트만 읽도록 `agent-ops/` 구조를 제공하는 프레임워크입니다.

핵심은 하나의 거대한 규칙 파일을 항상 읽는 방식이 아니라, 진입 규칙에서 프로젝트 규칙, 도메인 규칙, 스킬, 로드맵 문서를 필요한 순간에만 연결하는 것입니다.

## 구조

```text
agent-ops/
  bin/
    entry-files.sh
    init-agent-ops.sh
    sync.sh
    bump-version.sh
  rules/
    common/
      rules.md
    project/
      rules.md
      domain/<domain-name>/rules.md
    private/
      rules.md
  skills/
    common/
      router.md
      <skill-name>/SKILL.md
    project/
      <skill-name>/SKILL.md
  roadmap/
    ROADMAP.md
    current.md
    milestones/<milestone-slug>.md
```

`agent-ops/roadmap/`은 `create-roadmap` 실행 시 생성됩니다.

## 컨텍스트 로딩

에이전트 진입 파일(`CLAUDE.md`, `AGENTS.md`, `GEMINI.md` 등)은 `agent-ops/rules/common/rules.md`의 복사본입니다.

세션이 시작되면 에이전트는 프로젝트별 규칙인 `agent-ops/rules/project/rules.md`와 개인 규칙인 `agent-ops/rules/private/rules.md`를 1회 읽습니다. 파일이 없으면 무시합니다.

작업이 특정 코드 영역을 변경하면 `rules/project/rules.md`의 도메인 매핑을 기준으로 해당 `rules/project/domain/<domain>/rules.md`만 읽습니다.

스킬성 요청은 사용자가 명시적으로 요청했을 때 `agent-ops/skills/common/router.md`를 읽고, 매핑된 `SKILL.md` 하나를 실행합니다. 일반 작업마다 router와 모든 스킬을 자동으로 읽지 않습니다.

현재 작업 지점이나 남은 작업 질문은 `analyze-roadmap-position` 스킬이 `current.md`, 활성 Milestone 문서, git 상태, 변경 파일을 함께 보고 분석합니다.

## 공통 스킬

공통 스킬 라우팅은 `agent-ops/skills/common/router.md`가 단일 기준입니다.

| 스킬 | 역할 |
|------|------|
| `init-agent-ops` | 대상 프로젝트에 agent-ops 기본 구조, 진입 파일, 프로젝트 규칙, 도메인 규칙 초안을 생성 |
| `create-domain-rule` | 새 도메인 rules.md를 만들고 프로젝트 도메인 매핑에 추가 |
| `update-domain-rule` | 기존 도메인 rules.md를 코드 현황에 맞게 갱신 |
| `create-skill` | 새 공통 또는 프로젝트 스킬 생성 |
| `create-readme` | AI가 다음 작업에 활용할 수 있는 표준형 README 생성 |
| `create-roadmap` | 한국어 기반 Goal/Phase/Milestone 로드맵 생성 |
| `update-roadmap` | 기존 로드맵 상태, Milestone, Phase, 한국어 문서 형식 갱신 |
| `analyze-roadmap-position` | "지금 작업이 뭐지?" 같은 질문에 활성 Milestone과 코드 상태를 함께 분석 |
| `plan` | 구현 작업용 `PLAN-*-G??.md`와 `CODE_REVIEW-*-G??.md` 초안 생성 |
| `code-review` | plan-code-review 루프의 리뷰, 판정, archive, 후속 plan 생성 |
| `commit-push` | 변경 사항을 한국어 커밋 메시지로 커밋하고 푸시 |
| `sync-pull` | agentic-framework에서 현재 프로젝트로 agent-ops 내려받기 |
| `sync-push` | 현재 agent-ops를 agentic-framework 또는 대상 프로젝트로 push 동기화 |

## 로드맵

로드맵은 사람이 함께 검토하고 수정하는 협업 문서이므로 전체 구성과 설명 문장은 한국어로 작성합니다.

`Goal`, `Phase`, `Milestone`, `API`, `CLI` 같은 일반 개발 용어와 파일명, 경로, slug 같은 식별자는 영어 또는 숫자를 유지할 수 있습니다.

Phase와 Milestone에는 순번을 강제하지 않습니다. 진행 순서는 `ROADMAP.md`에 적힌 위에서 아래 순서로 봅니다. 새 작업을 추가할 때는 사용자가 지정한 위치를 우선하고, 단위 지정이 없으면 작업 성격을 보고 새 Milestone, 기존 Milestone의 태스크, 기존 태스크의 하위 작업 중 적절한 단위로 배치합니다.

로드맵 문서는 `agent-ops/skills/common/_templates/roadmap-template.md`, `roadmap-current-template.md`, `roadmap-milestone-template.md` 형식을 따릅니다. 해야 할 작업은 Milestone 문서의 `필수 기능` 체크리스트로, 완료 판단 조건은 `완료 기준` 체크리스트로 관리합니다.

일반 작업에서는 전체 `ROADMAP.md`를 매번 읽지 않습니다. 먼저 `current.md`의 활성 Milestone 창을 읽고, 요청 범위와 변경 파일에 맞는 Milestone 문서만 읽습니다.

## 적용

자세한 적용 절차는 [`agent-ops/GUIDE.md`](agent-ops/GUIDE.md)를 따릅니다.

간단히는 아래 흐름입니다.

1. 이 레포의 `agent-ops/` 폴더를 대상 프로젝트 루트에 복사합니다.
2. 에이전트에게 `agent-ops/skills/common/init-agent-ops/SKILL.md` 실행을 요청합니다.
3. 생성된 `rules/project/rules.md`와 도메인 규칙을 확인하고 보완합니다.
4. 반복 작업은 공통 스킬 또는 프로젝트 스킬로 정의합니다.
5. 공통 파일 변경은 agentic-framework에서 관리하고 `sync-push` / `sync-pull`로 동기화합니다.

## 관리 원칙

- 공통 파일은 agentic-framework에서 수정합니다.
- 대상 프로젝트에서는 `rules/project/`, `rules/private/`, `skills/project/`를 프로젝트에 맞게 수정합니다.
- `agent-ops/rules/common/`, `agent-ops/skills/common/`, `agent-ops/bin/`은 공통 관리 영역입니다.
- 공통 파일 변경 후에는 `agent-ops/.version`을 함께 관리하고 동기화합니다.

## 설계 효과

| 항목 | 내용 |
|------|------|
| 선택적 컨텍스트 | 작업에 필요한 규칙과 스킬만 읽어 컨텍스트 낭비를 줄임 |
| 프로젝트 적응 | 프로젝트별 규칙과 도메인 규칙으로 코드베이스별 차이를 반영 |
| 반복 작업 표준화 | 초기화, 도메인 규칙, 로드맵, 계획, 리뷰, 커밋, 동기화를 스킬로 고정 |
| 추적 가능성 | rules, skills, roadmap을 레포에서 버전 관리 |
| 확장성 | 공통 스킬과 프로젝트 스킬을 분리해 팀 표준과 프로젝트 특화를 함께 운영 |