221 lines
8.3 KiB
Markdown
221 lines
8.3 KiB
Markdown
# Agent Context를 구조적으로 제어하는 설계 방식
|
|
|
|
## 1. 배경: 왜 지금 Agent 설계가 중요한가
|
|
|
|
대부분의 팀이 AI 에이전트를 도입할 때 가장 먼저 겪는 문제는 품질의 불안정성이다.
|
|
|
|
에이전트가 때로는 팀 컨벤션을 따르고, 때로는 무시한다. 작업마다 결과물의 일관성이 다르다.
|
|
|
|
이 문제의 근본 원인은 에이전트에게 무엇을 읽어야 하는지를 알려주지 않았기 때문이다.
|
|
|
|
## 2. 핵심 아이디어: Agent Context를 구조적으로 제어한다
|
|
|
|
일반적인 접근은 하나의 큰 규칙 파일에 모든 것을 넣는 방식이다.
|
|
|
|
❌ 일반적인 방식
|
|
|
|
```
|
|
모든 규칙이 담긴 파일 → 매 작업마다 전체 로드
|
|
|
|
→ 관련 없는 규칙이 컨텍스트를 채움
|
|
→ 에이전트 집중도 저하
|
|
→ 품질 불안정
|
|
```
|
|
|
|
Agent Context Framework 방식은 다르다.
|
|
|
|
✅ Agent Context Framework 방식
|
|
|
|
```
|
|
작업 요청 → 라우터가 작업 유형 판별 → 필요한 파일 1개만 로드
|
|
|
|
→ 작업에 집중된 컨텍스트만 유지
|
|
→ 에이전트가 관련 규칙에만 집중
|
|
→ 품질 안정
|
|
```
|
|
|
|
LLM의 컨텍스트 윈도우는 유한하다. 관련 없는 내용이 많을수록 생성 품질이 떨어진다.
|
|
|
|
이 구조는 에이전트가 읽어야 할 컨텍스트를 사전에 분류하고, 선택적으로 로드하도록 설계한다.
|
|
|
|
## 3. 구조 설계
|
|
|
|
### 3계층 구성
|
|
|
|
```
|
|
agent-ops/
|
|
├── 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 # 프로젝트 스킬
|
|
```
|
|
|
|
### 실행 흐름
|
|
|
|
```
|
|
에이전트 요청 수신
|
|
↓
|
|
진입 파일 로드 (CLAUDE.md 등)
|
|
↓
|
|
project/rules.md + private/rules.md 로드
|
|
↓
|
|
스킬 요청인 경우: router.md → 해당 SKILL.md 1개만 로드
|
|
코드 변경인 경우: 도메인 매핑 테이블 → 해당 domain/rules.md 로드
|
|
↓
|
|
작업 실행
|
|
```
|
|
|
|
## 4. 설계 원칙
|
|
|
|
### 원칙 1. 단일 진입점 + 선택적 로드
|
|
|
|
에이전트는 시작 시 진입 파일(CLAUDE.md 등)을 읽고 project/rules.md를 로드한다.
|
|
|
|
스킬 키워드가 포함된 요청은 router.md를 통해 해당 SKILL.md 하나로 라우팅된다.
|
|
|
|
코드 변경 요청은 project/rules.md의 도메인 매핑 테이블을 통해 해당 domain/rules.md만 참조한다.
|
|
|
|
에이전트는 작업에 필요한 파일만 읽는다.
|
|
|
|
### 원칙 2. Skill의 자기완결성
|
|
|
|
각 SKILL.md는 실행 조건, 절차, 출력 형식을 모두 포함한다.
|
|
|
|
에이전트가 해당 파일 하나만 읽으면 작업을 완수할 수 있는 함수처럼 호출 가능한 단위다.
|
|
|
|
```markdown
|
|
---
|
|
name: skill-name
|
|
description: 어떤 요청에 이 스킬을 사용하는지 기술한다.
|
|
|
|
metadata:
|
|
version: 1.0.0
|
|
depends: [선행-스킬]
|
|
---
|
|
|
|
## 실행 절차
|
|
|
|
## 출력 형식
|
|
```
|
|
|
|
### 원칙 3. 도메인 기반 규칙 분리
|
|
|
|
프로젝트의 코드 구조와 동일한 기준으로 규칙을 도메인별로 분리한다.
|
|
|
|
project/rules.md의 도메인 매핑 테이블이 경로 패턴과 domain/rules.md를 연결하는 단일 출처(SSoT)다.
|
|
|
|
코드 수정 시 에이전트는 수정 대상이 어느 도메인인지 먼저 판별한 뒤, 해당 도메인 규칙만 참조한다.
|
|
|
|
잘못된 도메인 컨텍스트로 코드를 수정하는 실수를 구조적으로 방지한다.
|
|
|
|
### 원칙 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 내용을 에이전트별 파일명으로 진입 파일 생성 (CLAUDE.md 등)
|
|
7. (선택) rules/private/rules.md에 개인 규칙 작성 (git 제외)
|
|
|
|
구조는 공통이고, 내용은 프로젝트마다 다르다.
|
|
|
|
scaffold 구조를 팀 표준으로 공유하고, 각 프로젝트가 자신의 도메인과 Skill을 채워 넣는 방식으로 운영한다.
|
|
|
|
상세 적용 방법은 [`agent-ops/GUIDE.md`](agent-ops/GUIDE.md)를 참고한다.
|
|
|
|
## 8. 요약
|
|
|
|
| 항목 | 내용 |
|
|
|------|------|
|
|
| 핵심 아이디어 | 에이전트 컨텍스트를 라우팅으로 제어하고 필요한 파일만 선택 로드 |
|
|
| 구조 원칙 | 진입 파일 → project/rules.md → Skill / Domain rules 계층 분리 |
|
|
| 즉시 효과 | 루틴 자동화, 암묵지 문서화, 온보딩 단축, 코드 품질 기준선 확보 |
|
|
| 장기 효과 | 자율화 파이프라인 기반, 팀 간 공통 scaffold 표준화 |
|
|
| 적용 범위 | 기술 스택 무관, 모든 프로젝트에 동일한 구조 적용 가능 |
|