- Claude Code 에이전트 입력 스키마 설계는 Writer(스킬)와 Reader(에이전트) 간 데이터 계약을 정의하는 설계 작업
- 에이전트의 분석 품질이 입력 데이터 구조에 직접 의존하는 구조적 특성
- 입력 포맷, 출력 구조, context 효율을 함께 설계해야 하는 복합 문제
해당 개념이 필요한 이유
- 에이전트가 격리 컨텍스트에서 실행되므로, 입력 파일이 유일한 정보 소스
- 입력이 느슨하면 에이전트의 파싱/분석이 불안정해지고, 출력 품질이 하락
- context window는 유한하므로, 스키마를 어디에 두느냐가 토큰 비용에 직결
AS-IS
sequenceDiagram autonumber participant Skill as ai-dev-cycle (Skill) participant File as .retro-session.md participant Agent as retrospective-analyst Skill->>File: 자유 텍스트로 기록<br/>"[what user asked]" → technical, concept Note over File: 스키마 정의 없음<br/>파싱 규칙 없음 Agent->>File: Read (구조 추측하며 파싱) Note over Agent: trigger 필드 없음 → 우선순위 판정 불가<br/>질문 원문 유실 가능<br/>개념 중복 판정 기준 없음 Agent-->>Skill: 범용 회고 문서<br/>(User Learning = AI Improvement 동격)
TO-BE
sequenceDiagram autonumber participant Skill as ai-dev-cycle (Skill) participant File as .retro-session.md participant Agent as retrospective-analyst Skill->>File: 구조화된 테이블로 기록<br/>question|concept|category|trigger Note over File: Skill에 Writing rules 인라인<br/>Agent에 Parsing rules 인라인 Agent->>File: Read (명시적 파싱 규칙으로 처리) Note over Agent: trigger 필드 → 우선순위 자동 산정<br/>question 원문 보존<br/>concept exact match로 중복 처리 Agent-->>Skill: Study Keywords 중심 회고<br/>(학습 키워드 = 메인, AI Improvement = 부록)
문제 1: 입력 스키마 부재
에이전트는 격리 컨텍스트에서 실행되어 대화 히스토리에 접근할 수 없다. .retro-session.md 파일이 유일한 입력인데, 이 파일의 포맷이 정의되지 않으면 에이전트가 데이터를 안정적으로 파싱할 수 없다.
| 항목 | AS-IS | TO-BE |
|---|---|---|
| 포맷 | 자유 텍스트 bullet | 구조화된 markdown 테이블 |
| 질문 보존 | "[what user asked]" 자유 기술 | question 컬럼에 원문 보존 |
| trigger | 없음 | user-asked / ai-explained |
| 개념 세분화 | concept name 단일 | concept - sub-aspect |
| 패턴 집계 | (Nth occurrence) 수동 | pattern 동일 문자열 exact match |
| malformed 처리 | 없음 | skip + Summary 기록 |
Q) “왜 자유 텍스트가 아니라 테이블이어야 하는가?”
- 에이전트는 대화 맥락 없이 파일만 읽으므로, 구조가 파싱 규칙을 내포해야 한다
- 테이블은 컬럼 구분이 명확하여 pipe(
|) 기준으로 기계적 파싱이 가능 - 자유 텍스트는 AI가 “추측”해서 파싱 → 일관성 없는 결과
문제 2: 출력이 목적에 안 맞음
사용자의 핵심 목적은 **“내 질문에서 공부 키워드 추출”**인데, 기존 출력은 범용 회고 문서였다.
| 항목 | AS-IS | TO-BE |
|---|---|---|
| 메인 섹션 | ## User Learning (Business/Technical 분리) | ## Study Keywords (Priority별 정렬) |
| 질문 원문 | Context에 간접 서술 | Questions 컬럼에 원문 보존 |
| 등장 횟수 | 없음 | Count 컬럼 |
| 연관 키워드 | 없음 | Related Keywords (같은 커밋 동시 등장) |
| 학습 순서 | 없음 | Study Order (선행 → 후행 관계) |
| AI Improvement | 동격 | 부록으로 강등 |
문제 3: Context 효율 — 스키마를 어디에 둘 것인가
스키마 정의를 한 곳에 모으면 유지보수는 편하지만, 에이전트가 매번 Read로 불러와야 해서 context 토큰이 낭비된다.
3가지 접근법을 실험했다:
접근 1: 인라인 (초기)
SKILL.md ← 느슨한 포맷 인라인
Agent.md ← 스키마 없음 (추측 파싱)
- 문제: Writer와 Reader 간 계약 없음
접근 2: 별도 스키마 파일 참조
schema.md ← 정본
SKILL.md ← "schema.md 참조" (매 커밋마다 Read)
Agent.md ← "schema.md 참조" (에이전트 시작 시 Read)
- 문제: 커밋 4개 = 스킬 쪽에서 4회 추가 Read (토큰 낭비)
접근 3: 역할별 인라인 (최종 채택)
SKILL.md ← Writing template + rules 인라인 (자동 로드)
Agent.md ← Input_Schema + parsing rules 인라인 (자동 로드)
- 추가 Read: 0회
- 중복: 테이블 헤더 1줄뿐
- 각 컴포넌트가 자기 역할에 필요한 정보만 보유
| 접근법 | 유지보수 | 에이전트 추가 Read | 스킬 추가 Read (커밋 4개) |
|---|---|---|---|
| 인라인 (초기) | 1파일 | 0회 | 0회 |
| 별도 파일 참조 | 1파일 | 1회 | 4회 |
| 역할별 인라인 | 2파일 | 0회 | 0회 |
Q) “왜 별도 파일이 아니라 역할별 인라인인가?”
- Claude Code 에이전트는 프롬프트가 자동 로드됨 → 인라인이면 추가 tool call 없음
- 스킬은 메인 컨텍스트에서 실행 → SKILL.md 전체가 한 번에 로드됨
- 별도 파일은 매번 Read tool을 호출해야 하므로 context 토큰 + 레이턴시 이중 비용
설계 원칙 정리
| 원칙 | 설명 |
|---|---|
| Writer-Reader 계약 | 입력을 쓰는 쪽과 읽는 쪽이 동일한 스키마를 공유해야 한다 |
| 역할별 인라인 | 각 컴포넌트에 자기 역할에 필요한 정보만 인라인으로 두어 추가 Read를 제거한다 |
| trigger 필드 | user-asked vs ai-explained 구분으로 우선순위를 데이터 기반으로 산정한다 |
| 원문 보존 | 사용자 질문은 요약하지 않고 원문 그대로 보존한다 (회고 시 맥락 복원용) |
| 출력은 목적에 맞게 | ”범용 회고”가 아니라 사용자의 실제 목적(공부 키워드 추출)에 맞춰 구조를 설계한다 |
Flow을 다시 생각해보자. 모든 작업 완료 후 허락 받은 후 amend 정렬 진행하는 것으로
참고 문서
- Claude Code Skills — 스킬 시스템 전체 가이드