# Agent Context Framework

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

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

## 현재 상태

이 저장소는 `agent-ops/` 공통 파일의 원본 저장소입니다. 루트의 `.agent-ops-source` 마커가 있으므로 공통 규칙, 공통 스킬, 동기화 스크립트는 이 저장소에서 수정하고 다른 프로젝트로 배포합니다.

현재 프레임워크 버전은 `agent-ops/.version`에 기록되며, 이 README를 갱신한 시점의 버전은 `1.1.43`입니다. 이 저장소는 애플리케이션 런타임이 아니라 문서와 셸 스크립트 중심의 프레임워크라서 별도의 빌드나 테스트 설정 파일은 없습니다.

## 빠른 시작

대상 프로젝트에 공통 scaffold를 직접 배치하려면 이 저장소 루트에서 아래 명령을 실행합니다.

```bash
bash agent-ops/bin/init-agent-ops.sh /path/to/target-project
```

프로젝트 분석을 포함한 초기 세팅은 에이전트에게 정확한 스킬 경로를 지정해 요청합니다. 초기 세팅 전에는 진입 파일이 없을 수 있으므로 스킬 파일 경로를 직접 안내하는 편이 안전합니다.

```text
agent-ops/skills/common/init-agent-ops/SKILL.md 를 읽고 실행해줘.
```

스킬 실행 후에는 생성된 `agent-ops/rules/project/rules.md`와 `agent-ops/rules/project/domain/*/rules.md`를 프로젝트에 맞게 확인하고 보완합니다.

## 주요 명령

| 목적 | 명령 | 비고 |
|------|------|------|
| 공통 scaffold 배치 | `bash agent-ops/bin/init-agent-ops.sh /path/to/target-project` | source 저장소에서 대상 프로젝트로 공통 파일과 진입 파일을 배치 |
| 전체 sibling 프로젝트로 push 동기화 | `agent-ops/bin/sync.sh` | `agentic-framework`에서 실행하면 상위 폴더의 agent-ops 적용 프로젝트 전체에 반영 |
| 특정 프로젝트로 push 동기화 | `agent-ops/bin/sync.sh <target>` | 폴더명, 상대경로, 절대경로 사용 가능 |
| 대상 프로젝트에서 framework로 변경 올리기 | `agent-ops/bin/sync.sh agentic-framework` | 일반 프로젝트에서 실행 |
| framework에서 대상 프로젝트로 내려받기 | `agent-ops/bin/sync.sh --pull agentic-framework` | 일반 프로젝트에서 실행 |
| 버전 patch 증가 계산 | `agent-ops/bin/bump-version.sh <major.minor.patch>` | 결과 버전만 stdout으로 출력 |
| 작업 완료 버전 증가 | `next="$(agent-ops/bin/bump-version.sh "$(cat agent-ops/.version)")" && printf '%s\n' "$next" > agent-ops/.version` | 이 프로젝트에서 작업을 하나 완료할 때마다 실행. 단, agentic-framework 원본에서 다른 프로젝트로 agent-ops push 동기화만 수행할 때는 실행하지 않음 |

## 구조

```text
agent-ops/
  GUIDE.md
  .version
  bin/
    ai-ignore.sh
    entry-files.sh
    init-agent-ops.sh
    sync.sh
    bump-version.sh
  rules/
    common/
      rules.md
      rules-roadmap.md
      _templates/
        domain-rule-template.md
    project/
      rules.md
      domain/<domain-name>/rules.md
    private/
      rules.md
  skills/
    common/
      router.md
      _templates/
        skill-template.md
        roadmap-template.md
        roadmap-current-template.md
        roadmap-milestone-template.md
        roadmap-position-report-template.md
      <skill-name>/SKILL.md
    project/
      <skill-name>/SKILL.md
  roadmap/
    ROADMAP.md
    current.md
    milestones/<milestone-slug>.md
    archive/YYYY/MM/<milestone-slug>.md
```

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

## 진입 파일

`agent-ops/bin/entry-files.sh`가 초기화와 동기화에서 사용하는 진입 파일 목록의 단일 기준입니다.

| 에이전트 | 파일 |
|----------|------|
| Gemini | `GEMINI.md` |
| Claude | `CLAUDE.md` |
| Kilo Code / OpenCode | `AGENTS.md` |
| Cursor | `.cursorrules` |
| Cline | `.clinerules` |

각 진입 파일은 `agent-ops/rules/common/rules.md`의 복사본입니다. 동기화 시 대상 프로젝트의 기존 진입 파일 내용은 공통 규칙 내용으로 다시 적용됩니다.

## 컨텍스트 로딩

에이전트 진입 파일(`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회 읽습니다. 파일이 없으면 무시합니다.

프로젝트에 `agent-ops/roadmap/`이 있으면 세션 최초 1회 `agent-ops/rules/common/rules-roadmap.md`도 읽습니다.

작업이 특정 코드 영역을 변경하면 `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/roadmap/archive/**`는 완료 또는 폐기되어 현재 작업 후보에서 제외한 과거 Milestone 기록입니다. 일반 작업과 로드맵 분석에서는 읽지 않고, 사용자가 과거 기록 확인이나 복원을 명시적으로 요청한 경우에만 참조합니다.

## 공통 스킬

공통 스킬 라우팅은 `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, 한국어 문서 형식 갱신과 과거 Milestone 아카이빙 |
| `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 문서의 `필수 기능` 체크리스트로, 완료 판단 조건은 `완료 기준` 체크리스트로 관리합니다.

현재 작업 지점/남은 작업 분석 답변은 `agent-ops/skills/common/_templates/roadmap-position-report-template.md` 형식을 따릅니다.

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

완료 또는 폐기되어 현재 후보에서 제외할 과거 Milestone은 `agent-ops/roadmap/archive/YYYY/MM/`로 이동합니다. 이때 `ROADMAP.md`에는 `아카이브 Milestone 요약`만 남기고, 아카이브된 Milestone 문서는 아카이빙 당시 기록 스냅샷으로 보존하며 최신 스킬 규약에 맞춰 재포맷하지 않습니다.

## 적용

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

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

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

초기화와 framework에서 일반 프로젝트로 내려가는 동기화는 `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`를 에이전트가 기본적으로 읽지 않도록 각 도구별 ignore 또는 permission 파일도 함께 보강합니다.

## 동기화 흐름

`agent-ops/bin/sync.sh`는 현재 프로젝트가 `.agent-ops-source`를 가진 원본인지 여부에 따라 방향을 결정합니다.

| 실행 위치 | 명령 | 방향 |
|-----------|------|------|
| `agentic-framework` | `agent-ops/bin/sync.sh` | 원본에서 sibling 프로젝트 전체로 push |
| `agentic-framework` | `agent-ops/bin/sync.sh <target>` | 원본에서 특정 대상 프로젝트로 push |
| 일반 프로젝트 | `agent-ops/bin/sync.sh` | 현재 프로젝트의 공통 변경을 sibling `agentic-framework`로 push |
| 일반 프로젝트 | `agent-ops/bin/sync.sh --pull agentic-framework` | `agentic-framework` 공통 파일을 현재 프로젝트로 pull |

push 대상은 `agent-ops/.version`, `agent-ops/bin`, `agent-ops/rules/common`, `agent-ops/skills/common`, `entry-files.sh`에 정의된 진입 파일로 제한됩니다. 단, framework에서 일반 프로젝트로 내려보내는 push에서는 대상 프로젝트의 AI ignore / permission 파일을 덮어쓰지 않고 누락된 표준 설정만 보강하며, 버전을 올리지 않고 현재 `agent-ops/.version` 값을 그대로 전파합니다. 일반 프로젝트에서 framework로 올리는 push에서는 AI ignore / permission 파일을 보강하거나 stage하지 않으며, 공통 변경이 있으면 버전을 한 단계 올립니다.

## 관리 원칙

- 공통 파일은 agentic-framework에서 수정합니다.
- 대상 프로젝트에서는 `rules/project/`, `rules/private/`, `skills/project/`를 프로젝트에 맞게 수정합니다.
- `agent-ops/rules/common/`, `agent-ops/skills/common/`, `agent-ops/bin/`은 공통 관리 영역입니다.
- 공통 파일 변경 후에는 `agent-ops/.version`을 함께 관리하고 동기화합니다.
- 이 프로젝트에서 작업을 하나 완료할 때마다 `agent-ops/bin/bump-version.sh`로 `agent-ops/.version`을 한 단계 올립니다. 단, agentic-framework 원본에서 다른 프로젝트로 agent-ops push 동기화만 수행하는 작업에서는 버전을 올리지 않습니다.
- `agent-ops/rules/private/`는 개인 규칙 영역이며 대상 프로젝트의 `.gitignore`에 추가됩니다.

## 작업 맥락

AI 에이전트가 이 저장소를 이어서 작업할 때는 아래 경로를 먼저 확인하면 됩니다.

| 경로 | 역할 |
|------|------|
| `agent-ops/rules/common/rules.md` | 모든 에이전트 진입 파일의 원본 |
| `agent-ops/rules/common/rules-roadmap.md` | 로드맵 사용 프로젝트의 추가 공통 규칙 |
| `agent-ops/skills/common/router.md` | 요청 키워드와 공통 스킬 매핑 |
| `agent-ops/skills/common/*/SKILL.md` | 반복 작업별 실행 절차 |
| `agent-ops/bin/entry-files.sh` | 진입 파일 목록의 단일 기준 |
| `agent-ops/bin/sync.sh` | 공통 파일 push/pull 동기화 구현 |
| `agent-ops/GUIDE.md` | 대상 프로젝트 적용 가이드 |

## 설계 효과

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