docs: update README overview
This commit is contained in:
parent
6c62001193
commit
c213f83ae3
1 changed files with 73 additions and 193 deletions
266
README.md
266
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/<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/MNN-<milestone-slug>.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/<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을 레포에서 버전 관리 |
|
||||
| 확장성 | 공통 스킬과 프로젝트 스킬을 분리해 팀 표준과 프로젝트 특화를 함께 운영 |
|
||||
|
|
|
|||
Loading…
Reference in a new issue