# 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 표준화 |
| 적용 범위 | 기술 스택 무관, 모든 프로젝트에 동일한 구조 적용 가능 |