217 lines
14 KiB
Markdown
217 lines
14 KiB
Markdown
# Agent Context Framework
|
|
|
|
AI 에이전트가 매 작업마다 필요한 컨텍스트만 읽도록 `agent-ops/` 구조를 제공하는 프레임워크입니다.
|
|
|
|
핵심은 하나의 거대한 규칙 파일을 항상 읽는 방식이 아니라, 진입 규칙에서 프로젝트 규칙, 도메인 규칙, 스킬, 로드맵 문서를 필요한 순간에만 연결하는 것입니다.
|
|
|
|
## 현재 상태
|
|
|
|
이 저장소는 `agent-ops/` 공통 파일의 원본 저장소입니다. 루트의 `.agent-ops-source` 마커가 있으므로 공통 규칙, 공통 스킬, 동기화 스크립트는 이 저장소에서 수정하고 다른 프로젝트로 배포합니다.
|
|
|
|
현재 프레임워크 버전은 `agent-ops/.version`에 기록되며, 이 README를 갱신한 시점의 버전은 `1.1.68`입니다. 이 저장소는 애플리케이션 런타임이 아니라 문서와 셸 스크립트 중심의 프레임워크라서 별도의 빌드나 테스트 설정 파일은 없습니다.
|
|
|
|
## 빠른 시작
|
|
|
|
대상 프로젝트에 공통 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` | `.agent-ops-source`가 있는 원본 repo에서 실행하면 상위 폴더의 agent-ops 적용 프로젝트 전체에 반영 |
|
|
| 특정 프로젝트로 push 동기화 | `agent-ops/bin/sync.sh <target>` | 폴더명, 상대경로, 절대경로 사용 가능 |
|
|
| 대상 프로젝트에서 공통 원본 repo로 변경 올리기 | `agent-ops/bin/sync.sh agentic-framework` | 일반 프로젝트에서 실행 |
|
|
| 공통 원본 repo에서 대상 프로젝트로 내려받기 | `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` | 이 프로젝트에서 작업을 하나 완료할 때마다 실행. 단, 현재 프로젝트 루트에 `.agent-ops-source`가 있고 다른 프로젝트로 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/
|
|
philosophy.md
|
|
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-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-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`, `ROADMAP.md`의 Phase 흐름, 활성 Phase의 Milestone 흐름을 읽고 `로드맵 > Phase > Milestone` breadcrumb로 빠르게 표시합니다. 기본 동작에서는 코드, git 상태, diff를 읽지 않습니다.
|
|
|
|
`agent-roadmap/archive/**`는 완료 또는 폐기되어 현재 작업 후보에서 제외한 과거 Milestone 기록입니다. 일반 작업과 로드맵 분석에서는 읽지 않고, 사용자가 과거 기록 확인이나 복원을 명시적으로 요청한 경우에만 참조합니다.
|
|
|
|
## 설계 철학
|
|
|
|
agent-ops는 AI-first 작업 프레임워크입니다. 규칙, 스킬, 로드맵은 에이전트가 필요한 것만 읽고 바로 행동할 수 있게 짧고 명확해야 합니다.
|
|
|
|
세부 원칙은 [`agent-ops/rules/common/philosophy.md`](agent-ops/rules/common/philosophy.md)에서 관리합니다. 이 문서는 일반 작업 진입점이 아니라, agent-ops 구조나 책임 경계를 설계하고 수정할 때만 읽는 참조 문서입니다.
|
|
|
|
## 공통 스킬
|
|
|
|
공통 스킬 라우팅은 `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` | "지금 작업이 뭐지?" 같은 질문에 전체 로드맵상 현재 Phase/Milestone 좌표를 빠르게 표시 |
|
|
| `plan` | 구현 작업용 `PLAN-*-G??.md`와 `CODE_REVIEW-*-G??.md` 초안 생성 |
|
|
| `code-review` | plan-code-review 루프의 리뷰, 판정, archive, 후속 plan 생성 |
|
|
| `commit-push` | 변경 사항을 한국어 커밋 메시지로 커밋하고 푸시 |
|
|
| `sync-pull` | 공통 원본 repo에서 현재 프로젝트로 agent-ops 내려받기 |
|
|
| `sync-push` | 현재 agent-ops를 공통 원본 repo 또는 대상 프로젝트로 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` 형식을 따릅니다.
|
|
|
|
로드맵 현지점 확인에서는 `current.md`, `ROADMAP.md`의 Phase 흐름, 활성 Phase의 Milestone 흐름, 활성 Milestone의 제목/목표/상태만 기본으로 읽습니다.
|
|
|
|
완료 또는 폐기되어 현재 후보에서 제외할 과거 Milestone은 `agent-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. 공통 파일 변경은 `.agent-ops-source`가 있는 공통 원본 repo에서 관리하고 `sync-push` / `sync-pull`로 동기화합니다.
|
|
|
|
초기화와 `.agent-ops-source`가 있는 공통 원본 repo에서 일반 프로젝트로 내려가는 동기화는 `agent-task/archive/**`와 `agent-roadmap/archive/**`를 에이전트가 기본적으로 읽지 않도록 각 도구별 ignore 또는 permission 파일도 함께 보강합니다. 단, `agent-roadmap/archive/**`는 필요 시 링크로 읽을 수 있어야 하므로 hard read/glob deny가 아니라 ignore 또는 watcher ignore 기준으로만 관리합니다.
|
|
|
|
## 동기화 흐름
|
|
|
|
`agent-ops/bin/sync.sh`는 현재 프로젝트가 `.agent-ops-source`를 가진 원본인지 여부에 따라 방향을 결정합니다.
|
|
|
|
| 실행 위치 | 명령 | 방향 |
|
|
|-----------|------|------|
|
|
| 공통 원본 repo | `agent-ops/bin/sync.sh` | 원본에서 sibling 프로젝트 전체로 push |
|
|
| 공통 원본 repo | `agent-ops/bin/sync.sh <target>` | 원본에서 특정 대상 프로젝트로 push |
|
|
| 일반 프로젝트 | `agent-ops/bin/sync.sh` | 현재 프로젝트의 공통 변경을 sibling 공통 원본 repo로 push |
|
|
| 일반 프로젝트 | `agent-ops/bin/sync.sh --pull agentic-framework` | 공통 원본 repo의 공통 파일을 현재 프로젝트로 pull |
|
|
|
|
push 대상은 `agent-ops/.version`, `agent-ops/bin`, `agent-ops/rules/common`, `agent-ops/skills/common`, `entry-files.sh`에 정의된 진입 파일로 제한됩니다. 단, `.agent-ops-source`가 있는 공통 원본 repo에서 일반 프로젝트로 내려보내는 push에서는 대상 프로젝트의 AI ignore / permission 파일을 덮어쓰지 않고 누락된 표준 설정만 보강하며, 버전을 올리지 않고 현재 `agent-ops/.version` 값을 그대로 전파합니다. 일반 프로젝트에서 공통 원본 repo로 올리는 push에서는 AI ignore / permission 파일을 보강하거나 stage하지 않으며, 공통 변경이 있으면 버전을 한 단계 올립니다.
|
|
|
|
## 관리 원칙
|
|
|
|
- 공통 파일은 `.agent-ops-source`가 있는 공통 원본 repo에서 수정합니다.
|
|
- 대상 프로젝트에서는 `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`을 한 단계 올립니다. 단, 현재 프로젝트 루트에 `.agent-ops-source`가 있고 다른 프로젝트로 agent-ops push 동기화만 수행하는 작업에서는 버전을 올리지 않습니다.
|
|
- `agent-ops/rules/private/`는 개인 규칙 영역이며 대상 프로젝트의 `.gitignore`에 추가됩니다.
|
|
|
|
## 작업 맥락
|
|
|
|
AI 에이전트가 이 저장소를 이어서 작업할 때는 아래 경로를 먼저 확인하면 됩니다.
|
|
|
|
| 경로 | 역할 |
|
|
|------|------|
|
|
| `agent-ops/rules/common/rules.md` | 모든 에이전트 진입 파일의 원본 |
|
|
| `agent-ops/rules/common/philosophy.md` | agent-ops 구조와 문서 작성 원칙 |
|
|
| `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을 레포에서 버전 관리 |
|
|
| 확장성 | 공통 스킬과 프로젝트 스킬을 분리해 팀 표준과 프로젝트 특화를 함께 운영 |
|