Agent Context를 구조적으로 제어하는 설계 방식

1. 배경: 왜 지금 Agent 설계가 중요한가

대부분의 팀이 AI 에이전트를 도입할 때 가장 먼저 겪는 문제는 품질의 불안정성이다.

에이전트가 때로는 팀 컨벤션을 따르고, 때로는 무시한다. 작업마다 결과물의 일관성이 다르다.

이 문제의 근본 원인은 에이전트에게 무엇을 읽어야 하는지를 알려주지 않았기 때문이다.

2. 핵심 아이디어: Agent Context를 구조적으로 제어한다

일반적인 접근은 하나의 큰 규칙 파일에 모든 것을 넣는 방식이다.

❌ 일반적인 방식

모든 규칙이 담긴 파일 → 매 작업마다 전체 로드

→ 관련 없는 규칙이 컨텍스트를 채움
→ 에이전트 집중도 저하
→ 품질 불안정

Agent Context Framework 방식은 다르다.

✅ Agent Context Framework 방식

작업 요청 → 라우터가 작업 유형 판별 → 필요한 파일 1개만 로드

→ 작업에 집중된 컨텍스트만 유지
→ 에이전트가 관련 규칙에만 집중
→ 품질 안정

LLM의 컨텍스트 윈도우는 유한하다. 관련 없는 내용이 많을수록 생성 품질이 떨어진다.

이 구조는 에이전트가 읽어야 할 컨텍스트를 사전에 분류하고, 선택적으로 로드하도록 설계한다.

3. 구조 설계

3계층 구성

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 # 프로젝트 스킬

실행 흐름

에이전트 요청 수신
    ↓
진입 파일 로드 (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는 실행 조건, 절차, 출력 형식을 모두 포함한다.

에이전트가 해당 파일 하나만 읽으면 작업을 완수할 수 있는 함수처럼 호출 가능한 단위다.

---
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 내용을 agent-ops/bin/entry-files.sh의 파일 목록으로 진입 파일 생성
7. (선택) rules/private/rules.md에 개인 규칙 작성 (git 제외)

구조는 공통이고, 내용은 프로젝트마다 다르다.

scaffold 구조를 팀 표준으로 공유하고, 각 프로젝트가 자신의 도메인과 Skill을 채워 넣는 방식으로 운영한다.

상세 적용 방법은 agent-ops/GUIDE.md를 참고한다.

8. 요약

항목	내용
핵심 아이디어	에이전트 컨텍스트를 라우팅으로 제어하고 필요한 파일만 선택 로드
구조 원칙	진입 파일 → project/rules.md → Skill / Domain rules 계층 분리
즉시 효과	루틴 자동화, 암묵지 문서화, 온보딩 단축, 코드 품질 기준선 확보
장기 효과	자율화 파이프라인 기반, 팀 간 공통 scaffold 표준화
적용 범위	기술 스택 무관, 모든 프로젝트에 동일한 구조 적용 가능