diff --git a/README.md b/README.md index 0ad2a61..cebb53c 100644 --- a/README.md +++ b/README.md @@ -1,223 +1,103 @@ -# Agent Context를 구조적으로 제어하는 설계 방식 +# Agent Context Framework -## 1. 배경: 왜 지금 Agent 설계가 중요한가 +AI 에이전트가 매 작업마다 필요한 컨텍스트만 읽도록 `agent-ops/` 구조를 제공하는 프레임워크입니다. -대부분의 팀이 AI 에이전트를 도입할 때 가장 먼저 겪는 문제는 품질의 불안정성이다. +핵심은 하나의 거대한 규칙 파일을 항상 읽는 방식이 아니라, 진입 규칙에서 프로젝트 규칙, 도메인 규칙, 스킬, 로드맵 문서를 필요한 순간에만 연결하는 것입니다. -에이전트가 때로는 팀 컨벤션을 따르고, 때로는 무시한다. 작업마다 결과물의 일관성이 다르다. +## 구조 -이 문제의 근본 원인은 에이전트에게 무엇을 읽어야 하는지를 알려주지 않았기 때문이다. - -## 2. 핵심 아이디어: Agent Context를 구조적으로 제어한다 - -일반적인 접근은 하나의 큰 규칙 파일에 모든 것을 넣는 방식이다. - -❌ 일반적인 방식 - -``` -모든 규칙이 담긴 파일 → 매 작업마다 전체 로드 - -→ 관련 없는 규칙이 컨텍스트를 채움 -→ 에이전트 집중도 저하 -→ 품질 불안정 -``` - -Agent Context Framework 방식은 다르다. - -✅ Agent Context Framework 방식 - -``` -작업 요청 → 라우터가 작업 유형 판별 → 필요한 파일 1개만 로드 - -→ 작업에 집중된 컨텍스트만 유지 -→ 에이전트가 관련 규칙에만 집중 -→ 품질 안정 -``` - -LLM의 컨텍스트 윈도우는 유한하다. 관련 없는 내용이 많을수록 생성 품질이 떨어진다. - -이 구조는 에이전트가 읽어야 할 컨텍스트를 사전에 분류하고, 선택적으로 로드하도록 설계한다. - -## 3. 구조 설계 - -### 3계층 구성 - -``` +```text agent-ops/ - ├── bin/ - │ └── entry-files.sh # 진입 파일 목록의 단일 기준 - ├── rules/ - │ ├── common/ - │ │ └── rules.md # 진입 파일 템플릿 (에이전트별 파일명으로 복사) - │ ├── project/ - │ │ ├── rules.md # 프로젝트 특화 규칙 + 도메인 매핑 테이블 - │ │ └── domain/ - │ │ ├── {domain-a}/rules.md - │ │ ├── {domain-b}/rules.md - │ │ └── ... - │ └── private/ - │ └── rules.md # 개인 규칙 (git 제외, 선택) - └── skills/ - ├── common/ - │ ├── router.md # 공통 스킬 라우팅 테이블 - │ └── {skill-name}/SKILL.md - └── project/ - └── {skill-name}/SKILL.md # 프로젝트 스킬 + bin/ + entry-files.sh + init-agent-ops.sh + sync.sh + bump-version.sh + rules/ + common/ + rules.md + project/ + rules.md + domain//rules.md + private/ + rules.md + skills/ + common/ + router.md + /SKILL.md + project/ + /SKILL.md + roadmap/ + ROADMAP.md + current.md + milestones/MNN-.md ``` -### 실행 흐름 +`agent-ops/roadmap/`은 `create-roadmap` 실행 시 생성됩니다. -``` -에이전트 요청 수신 - ↓ -진입 파일 로드 (CLAUDE.md 등) - ↓ -project/rules.md + private/rules.md 로드 - ↓ -스킬 요청인 경우: router.md → 해당 SKILL.md 1개만 로드 -코드 변경인 경우: 도메인 매핑 테이블 → 해당 domain/rules.md 로드 - ↓ -작업 실행 -``` +## 컨텍스트 로딩 -## 4. 설계 원칙 +에이전트 진입 파일(`CLAUDE.md`, `AGENTS.md`, `GEMINI.md` 등)은 `agent-ops/rules/common/rules.md`의 복사본입니다. -### 원칙 1. 단일 진입점 + 선택적 로드 +세션이 시작되면 에이전트는 프로젝트별 규칙인 `agent-ops/rules/project/rules.md`와 개인 규칙인 `agent-ops/rules/private/rules.md`를 1회 읽습니다. 파일이 없으면 무시합니다. -에이전트는 시작 시 진입 파일(CLAUDE.md 등)을 읽고 project/rules.md를 로드한다. +작업이 특정 코드 영역을 변경하면 `rules/project/rules.md`의 도메인 매핑을 기준으로 해당 `rules/project/domain//rules.md`만 읽습니다. -스킬 키워드가 포함된 요청은 router.md를 통해 해당 SKILL.md 하나로 라우팅된다. +스킬성 요청은 사용자가 명시적으로 요청했을 때 `agent-ops/skills/common/router.md`를 읽고, 매핑된 `SKILL.md` 하나를 실행합니다. 일반 작업마다 router와 모든 스킬을 자동으로 읽지 않습니다. -코드 변경 요청은 project/rules.md의 도메인 매핑 테이블을 통해 해당 domain/rules.md만 참조한다. +현재 작업 위치 질문은 `agent-ops/roadmap/current.md`와 기본 Milestone 문서를 보고 짧게 답합니다. 변경 요청이 아니면 로드맵 파일을 수정하지 않습니다. -에이전트는 작업에 필요한 파일만 읽는다. +## 공통 스킬 -### 원칙 2. Skill의 자기완결성 +공통 스킬 라우팅은 `agent-ops/skills/common/router.md`가 단일 기준입니다. -각 SKILL.md는 실행 조건, 절차, 출력 형식을 모두 포함한다. +| 스킬 | 역할 | +|------|------| +| `init-agent-ops` | 대상 프로젝트에 agent-ops 기본 구조, 진입 파일, 프로젝트 규칙, 도메인 규칙 초안을 생성 | +| `create-domain-rule` | 새 도메인 rules.md를 만들고 프로젝트 도메인 매핑에 추가 | +| `update-domain-rule` | 기존 도메인 rules.md를 코드 현황에 맞게 갱신 | +| `create-skill` | 새 공통 또는 프로젝트 스킬 생성 | +| `create-roadmap` | 한국어 기반 Goal/Phase/Milestone 로드맵 생성 | +| `update-roadmap` | 기존 로드맵 상태, Milestone, Phase, 한국어 문서 형식 갱신 | +| `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 동기화 | -에이전트가 해당 파일 하나만 읽으면 작업을 완수할 수 있는 함수처럼 호출 가능한 단위다. +## 로드맵 -```markdown ---- -name: skill-name -description: 어떤 요청에 이 스킬을 사용하는지 기술한다. +로드맵은 사람이 함께 검토하고 수정하는 협업 문서이므로 전체 구성과 설명 문장은 한국어로 작성합니다. -metadata: - version: 1.0.0 - depends: [선행-스킬] ---- +`Goal`, `Phase`, `Milestone`, `API`, `CLI` 같은 일반 개발 용어와 파일명, 경로, Milestone ID, slug 같은 식별자는 영어 또는 숫자를 유지할 수 있습니다. -## 실행 절차 +일반 작업에서는 전체 `ROADMAP.md`를 매번 읽지 않습니다. 먼저 `current.md`를 읽고, 요청 범위에 맞는 기본 또는 진행 중인 Milestone 문서만 읽습니다. -## 출력 형식 -``` +## 적용 -### 원칙 3. 도메인 기반 규칙 분리 +자세한 적용 절차는 [`agent-ops/GUIDE.md`](agent-ops/GUIDE.md)를 따릅니다. -프로젝트의 코드 구조와 동일한 기준으로 규칙을 도메인별로 분리한다. +간단히는 아래 흐름입니다. -project/rules.md의 도메인 매핑 테이블이 경로 패턴과 domain/rules.md를 연결하는 단일 출처(SSoT)다. +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`을 함께 관리하고 동기화합니다. -### 원칙 4. 규칙을 코드처럼 관리 - -모든 rules.md와 SKILL.md는 소스코드와 함께 레포에서 버전 관리된다. - -``` -규칙 변경 = PR 생성 → 코드 리뷰와 동일한 프로세스 - -→ 규칙 자체가 팀 합의를 거친 문서가 됨 -→ 변경 이력이 git log로 추적 가능 -→ 브랜치별 규칙 실험 가능 -``` - -## 5. 기존 소프트웨어 설계 패턴과의 대응 - -이 구조가 낯설지 않은 이유는 개발자에게 익숙한 설계 패턴을 에이전트 설정에 그대로 적용했기 때문이다. - -| 소프트웨어 패턴 | Agent Context 대응 | -|----------------|-------------------| -| Router / Dispatcher | router.md — 요청을 분류해 적절한 Skill로 전달 | -| Strategy Pattern | 도메인별 rules.md — 같은 작업도 도메인에 따라 다른 규칙 적용 | -| Command Pattern | 각 SKILL.md — 자기완결적 실행 단위 | -| Service Locator | project/rules.md 도메인 매핑 테이블 — 도메인 매핑의 단일 출처(SSoT) | -| Separation of Concerns | common rules / project rules / domain rules / skills 계층 분리 | -| Open/Closed Principle | 기존 파일 수정 없이 새 Skill 추가로 기능 확장 | - -## 6. 도입으로 얻는 이득 - -### 이득 1. 루틴 작업 자동화 - -팀마다 반복되는 작업 패턴이 있다. 빌드, 배포, 코드 생성, 분석, 버전 관리 등이 이에 해당한다. - -이 패턴들을 Skill로 정의하면 에이전트가 일관된 방식으로 실행한다. - -명령어를 기억하거나 문서를 찾을 필요 없이, 자연어 요청 한 마디로 실행된다. - -### 이득 2. 암묵지의 문서화 - -팀 시니어 개발자의 머릿속에만 있던 "우리 팀은 이렇게 한다"가 rules.md로 명문화된다. - -신규 팀원은 에이전트를 통해 팀 컨벤션을 자연스럽게 습득할 수 있다. - -온보딩 비용이 줄고, 담당자 부재 시에도 일관된 코드 생성이 가능해진다. - -### 이득 3. 코드 품질의 바닥 상승 - -에이전트가 rules.md를 참조하여 코드를 생성하면, 팀 컨벤션에서 벗어난 코드가 줄어든다. - -모든 팀원이 동일한 규칙을 적용받는 환경이 만들어진다. - -### 이득 4. 확장이 쉽다 - -새로운 작업 유형이 생기면 SKILL.md 파일 1개를 추가하고 router.md에 한 줄을 등록하면 된다. - -기존 파일을 건드리지 않으므로 팀원 간 충돌이 적고, 각자 독립적으로 기여할 수 있다. - -### 이득 5. 자율화 파이프라인의 토대 - -현재는 에이전트 보조 + 사람 검토 방식이지만, 이 구조는 처음부터 자율화를 염두에 둔 설계다. - -``` -현재 -에이전트 작업 → 사람 검토 → 반영 - -목표 -에이전트 작업 → 자동 검증 → 자동 반영 -``` - -라우팅 구조, Skill의 자기완결성, 레포 기반 규칙 관리는 모두 이 파이프라인의 인프라로서 기능한다. - -검증 Skill(빌드, 테스트, 코드 리뷰)을 추가하는 것만으로 자율화 단계로 이행할 수 있다. - -## 7. 다른 프로젝트에 적용하는 방법 - -이 구조는 특정 기술 스택에 종속되지 않는다. 어떤 프로젝트에도 동일한 방식으로 적용할 수 있다. - -1. `agent-ops/` 폴더를 프로젝트 루트에 복사 -2. 프로젝트의 코드 구조를 도메인으로 분리 -3. 도메인별 rules.md 작성 -4. 반복 작업을 SKILL.md로 정의 -5. router.md에 작업 유형별 매핑 등록 -6. rules/common/rules.md 내용을 `agent-ops/bin/entry-files.sh`의 파일 목록으로 진입 파일 생성 -7. (선택) rules/private/rules.md에 개인 규칙 작성 (git 제외) - -구조는 공통이고, 내용은 프로젝트마다 다르다. - -scaffold 구조를 팀 표준으로 공유하고, 각 프로젝트가 자신의 도메인과 Skill을 채워 넣는 방식으로 운영한다. - -상세 적용 방법은 [`agent-ops/GUIDE.md`](agent-ops/GUIDE.md)를 참고한다. - -## 8. 요약 +## 설계 효과 | 항목 | 내용 | |------|------| -| 핵심 아이디어 | 에이전트 컨텍스트를 라우팅으로 제어하고 필요한 파일만 선택 로드 | -| 구조 원칙 | 진입 파일 → project/rules.md → Skill / Domain rules 계층 분리 | -| 즉시 효과 | 루틴 자동화, 암묵지 문서화, 온보딩 단축, 코드 품질 기준선 확보 | -| 장기 효과 | 자율화 파이프라인 기반, 팀 간 공통 scaffold 표준화 | -| 적용 범위 | 기술 스택 무관, 모든 프로젝트에 동일한 구조 적용 가능 | +| 선택적 컨텍스트 | 작업에 필요한 규칙과 스킬만 읽어 컨텍스트 낭비를 줄임 | +| 프로젝트 적응 | 프로젝트별 규칙과 도메인 규칙으로 코드베이스별 차이를 반영 | +| 반복 작업 표준화 | 초기화, 도메인 규칙, 로드맵, 계획, 리뷰, 커밋, 동기화를 스킬로 고정 | +| 추적 가능성 | rules, skills, roadmap을 레포에서 버전 관리 | +| 확장성 | 공통 스킬과 프로젝트 스킬을 분리해 팀 표준과 프로젝트 특화를 함께 운영 |