Web Dev Learn

Theme

11-3. 컨텍스트 엔지니어링과 프로젝트 지시문 ​

한 줄 요약: 컨텍스트 윈도우를 유한한 예산으로 이해하고, 프로젝트 지시문·메모리·문서를 에이전트가 소비 가능한 저장소 계약으로 설계·관리할 수 있다.

학습 목표 ​

  • 컨텍스트 윈도우의 동작 모델(예산, 누적, 압축, 오염)로 "작게 시켜라"류 팁의 근거를 설명할 수 있다.
  • 작업 프롬프트에 쓸 정보와 저장소 지시문으로 관리할 정보를 구분할 수 있다.
  • AGENTS.md/CLAUDE.md/rules/memories를 제품 기능이 아니라 저장소 계약으로 설계하고 관리할 수 있다.
  • 프론트엔드 저장소를 agent-ready 상태로 만드는 문서 구조를 구성할 수 있다.
  • 프론트엔드가 소비하는 API 계약 문서를 에이전트가 읽을 수 있는 품질로 유지하는 기준을 설명할 수 있다.

배경: 왜 이것이 존재하는가 ​

에이전트에 대한 흔한 실망은 "우리 코드베이스를 이해하지 못한다"는 것이다. 그런데 이 문장을 뒤집어 보자. 새로 합류한 시니어 개발자가 첫 주에 저장소를 이해하지 못한다면, 우리는 그의 능력보다 온보딩 문서의 부재를 의심한다. 에이전트는 매 세션이 첫 출근이다. 어제 세션에서 알아낸 빌드 명령, 디렉터리 규칙, 팀의 금기는 오늘 세션에 남아 있지 않다. 세션 간 기억이 없는 시스템에게 지속되는 지식을 공급하는 유일한 통로는 저장소 안의 파일이고, 이 통로를 설계하는 일이 컨텍스트 엔지니어링(context engineering)이다.

프롬프트 엔지니어링과의 차이를 명확히 하자. 프롬프트 엔지니어링이 한 번의 요청 문구를 다듬는 일이라면, 컨텍스트 엔지니어링은 모델이 매 판단 시점에 보는 정보 전체 — 시스템 지시문, 저장소 지시문, 읽은 파일, 도구 정의, 대화 이력, 실패 로그 — 를 무엇을 넣고, 무엇을 빼고, 무엇을 언제 공급할지 설계하는 일이다. 경력 개발자에게 이 일은 낯설지 않다. 요구사항 문서, ADR, 온보딩 가이드, runbook을 쓰는 일의 연장이며, 소비자가 사람에서 기계로 확장됐을 뿐이다. 그리고 오래된 진실이 여기서도 성립한다: 사람에게 불명확한 문서는 에이전트에게도 불명확하다.

핵심 개념 ​

컨텍스트 윈도우는 유한한 예산이다 ​

모델이 한 번의 추론에서 볼 수 있는 토큰 수(컨텍스트 윈도우)는 유한하다. 수십만 토큰 규모의 윈도우도 중간 규모 저장소의 소스 전체보다 작고, 무엇보다 11-1에서 봤듯 루프가 돌 때마다 대화 이력 전체가 다시 입력된다. 세션에서 일어나는 일을 예산 관점에서 추적하면 이렇다.

text
세션 시작:  [시스템 지시문][저장소 지시문][도구 정의]        ← 고정 지출
루프 1:     + [작업 명세]
루프 2:     + [파일 A 내용][파일 B 내용]                    ← 탐색 비용
루프 5:     + [테스트 실행 출력 (실패 로그 300줄)]
루프 9:     + [편집 diff][재실행 출력][다른 접근의 실패 로그]
루프 15:    예산 압박 → 하네스가 오래된 이력을 압축(compaction)

세 가지 귀결이 실무 판단으로 이어진다.

첫째, 압축은 손실 압축이다. 예산이 차면 하네스는 오래된 대화를 요약으로 대체한다. 요약은 "무엇을 했는가"는 보존해도 "왜 그 접근을 폐기했는가", "어느 파일의 몇 번째 줄이었는가" 같은 세부를 잃는다. 긴 세션 후반에 에이전트가 이미 시도해서 실패한 접근을 다시 꺼내거나, 앞서 합의한 제약을 잊는 현상의 상당 부분이 여기서 온다.

둘째, 컨텍스트는 오염(pollution)된다. 예산이 남아 있어도 품질이 떨어질 수 있다. 무관한 파일 내용, 반복된 실패 로그, 폐기된 접근의 흔적, 모순된 지시("아까는 A라고 했다가 지금은 B")가 쌓이면, 모델은 현재 판단에 무관하거나 유해한 정보까지 주의(attention)를 배분한다. 특히 실패 로그가 여러 번 쌓인 세션에서는 실패한 패턴 자체가 컨텍스트 안에서 반복 노출되어 모델이 그 패턴으로 회귀하는 경향이 관찰된다. 11-2에서 "같은 오해를 두 번 교정했다면 새 세션에서 시작하라"고 한 근거가 이것이다.

셋째, "작게 시켜라"의 정량적 근거가 나온다. 작업이 작다는 것은 필요한 파일·이력·시행착오가 예산 안에 압축 없이 들어간다는 뜻이다. 세션 인계가 필요할 만큼 작업이 길어지면, 인계는 암묵에 맡기지 말고 명시적 산출물로 만든다: 현재 상태, 완료된 것, 남은 것, 확정된 결정과 근거, 주의사항을 파일로 쓰게 하고 새 세션의 입력으로 준다.

정보의 자리: 프롬프트, 지시문, 문서, 메모리 ​

같은 정보라도 놓이는 자리에 따라 수명과 도달 범위가 다르다. 컨텍스트 엔지니어링의 절반은 이 배치 결정이다.

자리수명로드 시점적합한 정보
작업 프롬프트한 세션세션 시작이번 작업의 목표, 범위, 성공 조건
저장소 지시문 (AGENTS.md/CLAUDE.md)영속, 커밋됨매 세션 자동실행 명령, 구조, 불변 규칙, 금지 사항
저장소 문서 (README, ADR, 설계 문서)영속, 커밋됨에이전트가 필요 시 탐색배경, 결정 이력, 도메인 설명
메모리(memories)영속, 도구가 관리관련성 기반 회상세션에서 학습된 프로젝트 규칙
rules / skills / prompt template영속, 커밋됨조건부(경로·명령 매칭)특정 파일 유형·작업 유형의 절차

배치 원칙은 다음과 같다.

  • 매 작업에 항상 유효한 최소 정보만 지시문에 넣는다. 지시문은 매 세션 고정 지출이다. 300줄짜리 지시문은 매 루프마다 예산을 차지하며, 대부분의 작업에 무관한 내용이 절반이면 그 절반은 순수 오염이다.
  • 필요할 때만 유효한 정보는 문서로 두고 지시문에서 링크한다. "상태 관리 규칙은 docs/adr/003-state.md 참고"가 규칙 전문 인라인보다 낫다. 에이전트는 링크를 따라 필요할 때 읽는다.
  • 일회성 정보는 어디에도 저장하지 않는다. 이번 작업의 판단은 작업 리포트나 PR 설명에 남긴다. 그것이 다음에 또 유효하다면 그때 지시문·메모리로 승격한다.

저장소 지시문은 계약이다 ​

AGENTS.md(Codex 등 다수 도구가 읽는 사실상의 공통 규약)와 CLAUDE.md(Claude Code)는 기능은 같다: 세션 시작 시 자동으로 컨텍스트에 들어가는 저장소 상주 지시문이다. 이를 제품별 마법 파일이 아니라 **저장소 계약(contract)**으로 다루는 것이 이 문서의 핵심 주장이다. 계약으로 다룬다는 것은 구체적으로:

  • 버전 관리와 리뷰를 거친다. 지시문 변경은 코드 변경과 같은 PR 절차를 밟는다. 지시문의 한 줄이 이후 모든 에이전트 세션의 행동을 바꾸므로, 영향 범위는 웬만한 코드 변경보다 넓다.
  • 단일 원본을 유지한다. 여러 도구를 쓰는 팀이 AGENTS.md와 CLAUDE.md에 다른 내용을 두면 도구에 따라 에이전트가 다른 규칙을 따르는 분열이 생긴다. 하나를 원본으로 삼고 다른 하나는 원본을 가리키게 하거나(symlink 또는 "AGENTS.md를 따른다" 한 줄), 생성 스크립트로 동기화한다.
  • 검증 가능한 문장으로 쓴다. "코드를 깨끗하게 유지한다" 같은 문장은 계약이 아니다. "스타일은 pnpm lint가 판정한다", "src/legacy/는 수정하지 않는다"처럼 준수 여부를 판정할 수 있게 쓴다.

효과적인 지시문의 구성은 저장소마다 다르지만, 프론트엔드 저장소의 최소 골격은 다음과 같다.

md
# AGENTS.md

## 프로젝트 개요
주문 관리 SPA. React 19 + TypeScript + Vite. 상태는 TanStack Query(서버) +
zustand(클라이언트)로 분리한다. 구조 배경은 docs/adr/ 참고.

## 명령
- 개발 서버: `pnpm dev` (포트 5173)
- 검증: `pnpm typecheck && pnpm lint && pnpm test`
- e2e: `pnpm test:e2e` (dev 서버 필요)
- 단일 테스트: `pnpm test <파일명 일부>`

## 구조
- `src/features/<도메인>/` — 도메인별 컴포넌트·훅·테스트가 함께 위치
- `src/shared/` — 공용 UI. 여기 변경은 전체 영향이므로 별도 승인 필요
- `src/api/` — 생성된 API 클라이언트. 직접 수정 금지, `pnpm codegen`으로 재생성

## 규칙
- 서버 데이터를 useState로 복제하지 않는다 (ADR-003)
- 인터랙티브 요소는 접근 가능한 이름을 가져야 한다. `pnpm test:a11y`로 검증
- 커밋 전 `pnpm typecheck && pnpm lint` 필수

## 하지 말 것
- `src/api/` 수동 편집, `.env*` 읽기·수정, 테스트 skip 처리

무엇이 들어갔는지보다 무엇이 안 들어갔는지를 보라. 코딩 스타일 세부(린터가 판정한다), 일반적 모범 사례(모델이 이미 안다), 프레임워크 사용법(공식 문서의 영역)은 없다. 들어간 것은 이 저장소에서만 참인 것, 그리고 도구로 판정할 수 없어 문장으로 남겨야 하는 것뿐이다.

컨텍스트 선택: 전체가 아니라 목적별 절편 ​

"저장소 전체를 읽고 시작하라"는 지시는 예산 낭비이자 오염원이다. 에이전트의 탐색 능력을 신뢰하되, 작업 유형별로 좋은 출발점을 공급하는 것이 효율적이다.

  • 버그 수정: 재현 절차 + 관련 feature 디렉터리 + 최근 관련 diff(git log -p -- <경로>)
  • 기능 추가: 요구사항 + 가장 닮은 기존 feature의 경로("src/features/orders/와 같은 구조로")
  • 리팩터링: 대상 경로 + 해당 영역 테스트 + 관련 ADR
  • API 연동: API 계약 문서 + 기존 클라이언트 사용 예 1곳

"가장 닮은 기존 코드의 경로"는 특히 효율이 좋다. 모델은 예시 모방에 강하므로, 잘 만든 기존 feature 하나가 규칙 열 줄보다 코드 관례를 정확히 전달한다. 역으로 저장소에서 가장 낡은 코드를 에이전트가 먼저 읽으면 그 관례가 복제된다 — 탐색 출발점 공급이 중요한 이유다.

프론트엔드 저장소를 agent-ready로 만들기 ​

에이전트가 프론트엔드 작업에서 반복적으로 필요로 하는 정보를 찾기 쉬운 위치에 두는 것이 준비의 실체다.

  • 컴포넌트 구조와 소유권: 어떤 디렉터리가 무엇을 소유하는지, 공용 컴포넌트의 변경 절차는 무엇인지.
  • 상태 소유권 지도: 어떤 상태가 서버 상태(캐시 키 규칙 포함)이고, 무엇이 클라이언트 상태이고, 무엇이 URL에 있는지. 5-6/5-8에서 세운 구분이 에이전트에게는 명문화된 규칙으로 필요하다.
  • 디자인 토큰과 스타일 규칙: 색·간격을 하드코딩하지 말고 어떤 토큰을 쓸지. 에이전트는 명시가 없으면 임의 hex 값을 쓴다.
  • 접근성 기준: 요구 수준(예: WCAG 2.1 AA), 검증 명령, 커스텀 위젯의 참조 구현 위치.
  • 브라우저 지원 범위: Baseline 기준 또는 browserslist. 없으면 에이전트는 최신 API를 자유롭게 쓴다.
  • API 계약: OpenAPI 스키마나 생성된 타입의 위치, 갱신 명령.

이 목록이 "좋은 온보딩 문서" 목록과 같다는 점을 다시 확인하라. agent-ready 작업의 대부분은 원래 했어야 할 문서화이며, 에이전트는 그것을 미룰 수 없게 만드는 강제 장치다.

Agent-ready API 문서 ​

프론트엔드 에이전트의 주요 소비 문서 중 하나가 API 계약이다. 여기서 주의할 점: 사람이 읽기에 충분한 OpenAPI 문서도 에이전트 소비에는 미달일 수 있다. Hermes 연구(OpenAPI 문서와 REST API의 스멜을 다중 에이전트로 점검하는 시스템, 참고 자료)가 이 격차를 다룬다. 사람은 status 필드의 설명이 없어도 팀 지식과 네이밍에서 의미를 메우지만, 에이전트는 문서에 적힌 것만 안다. 에이전트 소비 관점의 점검 기준:

  • 스키마가 실제 응답과 일치하는가(문서 드리프트). 사람은 드리프트를 경험으로 보정하지만 에이전트는 문서를 믿고 코드를 만든다.
  • 모든 필드에 타입뿐 아니라 의미·단위·제약이 있는가. amount: number는 통화 단위와 소수 정밀도가 없으면 미완성이다.
  • 오류 응답이 상태 코드별로 스키마화되어 있는가. 에이전트가 만드는 오류 처리 코드의 품질은 오류 문서의 품질에 정확히 비례한다.
  • enum 값의 전체 목록과 각 값의 의미가 있는가.

프론트엔드 팀이 API 문서 품질에 대해 백엔드 팀과 협상할 때, "에이전트가 이 문서로 클라이언트 코드를 생성하다 실패한 기록"은 구체적이고 강력한 근거가 된다.

메모리: 축적과 부패 ​

여러 하네스가 세션을 넘어 유지되는 메모리 기능을 제공한다. 운영 원칙은 캐시 운영과 같다 — 축적보다 무효화가 어렵다.

  • 반복 검증된 규칙만 저장한다. 한 세션의 판단을 바로 저장하면 일회성 맥락이 영속 규칙으로 굳는다.
  • 틀린 메모리는 적극적으로 삭제한다. 저장소는 변한다. "테스트는 npm test로 실행"이라는 메모리는 pnpm 전환 후 유해하다. 메모리가 원인인 오동작은 저장소 어디에도 원인이 안 보이므로 디버깅이 특히 어렵다 — 에이전트가 이유 없이 이상하게 행동하면 메모리를 열람 대상에 넣어라.
  • 팀 공유가 필요한 규칙은 메모리가 아니라 지시문으로 승격한다. 메모리는 개인·머신 로컬인 경우가 많아, 팀 계약이 개인 메모리에만 있으면 팀원마다 에이전트가 다르게 동작한다.

컨텍스트 품질의 검증 ​

컨텍스트 공급이 잘 됐는지도 검증 대상이다. 유용한 프로브(probe) 세 가지:

  • 가정 보고: "구현 전에 네가 세운 가정과 확인하지 못한 것을 목록으로 보고하라." 가정 목록에서 컨텍스트 구멍이 드러난다.
  • 읽기 목록 확인: 하네스 로그에서 에이전트가 읽은 파일을 본다. 핵심 ADR을 안 읽고 구현했다면, 그 문서는 찾기 어려운 위치에 있는 것이다.
  • 신입 테스트: 저장소를 처음 보는 에이전트에게 "이 프로젝트의 실행·검증 방법과 구조를 설명하라"고 시킨다. 답의 오류가 곧 지시문·문서의 결함 목록이다. 온보딩 문서를 신입에게 검증받는 것과 같은 방법이며, 에이전트는 이 테스트를 언제든 몇 분 안에 돌 수 있게 해 준다.

실무 관점 ​

지시문 안티패턴 ​

안티패턴증상교정
백과사전형 지시문 (수백 줄)매 세션 고정 지출 증가, 핵심 규칙이 묻힘항상-유효 최소 규칙만 남기고 나머지는 링크
소망 목록형 규칙 ("좋은 코드를 쓴다")판정 불가, 행동 변화 없음도구가 판정하게 하거나 구체 행동으로 재서술
도구별 지시문 분열도구에 따라 다른 규칙 적용단일 원본 + 참조/동기화
지시문 방치명령·구조가 실제와 어긋나 에이전트가 오동작지시문을 계약으로: 구조 변경 PR에 지시문 갱신 포함
프롬프트에 모든 걸 반복매번 같은 배경을 타이핑반복되는 내용은 지시문·템플릿으로 승격

특히 방치가 흔하다. 지시문의 드리프트는 API 문서의 드리프트와 같은 문제이며, 같은 처방이 통한다: 리뷰 체크리스트에 "이 변경으로 지시문이 낡아지는가"를 넣는다.

컨텍스트를 늘릴 것인가 줄일 것인가 ​

컨텍스트 윈도우가 세대마다 커지면서 "다 넣으면 되지 않나"는 질문이 나온다. 트레이드오프로 답할 수 있다. 넣는 정보가 늘수록 (a) 비용과 지연이 커지고(입력 토큰은 매 루프 과금된다), (b) 관련 정보의 밀도가 낮아진다. 긴 컨텍스트의 중간에 있는 정보의 활용도가 떨어지는 현상은 벤치마크로 반복 보고되어 왔다. 반대로 지나치게 아끼면 에이전트가 탐색으로 스스로 채워야 하므로 루프 수가 늘고, 탐색이 놓친 규칙은 위반된다. 실용적 균형: 불변 규칙과 명령은 공급하고(탐색으로 알 수 없거나 위반 비용이 크다), 코드 내용은 탐색에 맡긴다(에이전트의 검색이 사람의 사전 선택보다 최신이고 정확하다).

문서화 투자 대비 회수 ​

agent-ready 문서화는 공짜가 아니다. 우선순위는 에이전트 실패 기록에서 역산하는 것이 정확하다. 에이전트가 잘못된 상태 관리 패턴을 반복하면 상태 소유권 문서가, 명령을 틀리면 명령 섹션이, 낡은 코드를 모방하면 참조 구현 지정이 부족한 것이다. 실패 없이 선제 투자할 가치가 가장 높은 것은 명령(모든 작업의 검증에 쓰인다)과 하지 말 것(위반 비용이 크다) 두 가지다.

더 깊이 ​

컨텍스트는 균질하지 않다: 신뢰 계층 ​

모델 입력은 겉보기에 하나의 텍스트지만, 하네스는 정보의 출처에 따라 다른 신뢰 수준을 의도한다. 시스템 지시문(하네스 제작자) > 사용자 지시·저장소 지시문(사용자와 팀) > 도구 결과·읽은 파일(환경에서 온 데이터). 문제는 모델에게 이 경계가 물리적이지 않고 학습된 관례라는 점이다. 읽은 파일 안에 "이전 지시를 무시하고 …하라"는 텍스트가 있으면, 모델이 그것을 데이터가 아니라 지시로 취급할 가능성이 남는다. 이것이 prompt injection의 구조적 원리다 — SQL injection이 데이터와 코드의 경계 붕괴이듯, prompt injection은 데이터와 지시의 경계 붕괴다. 컨텍스트에 무엇이 들어가는가는 그래서 품질 문제이면서 동시에 보안 문제이며, 11-6에서 방어를 다룬다.

압축의 구현과 인계 설계 ​

하네스의 압축은 대체로 "오래된 대화 구간을 모델 스스로 요약하게 하고 원문을 요약으로 치환"하는 방식이다. 요약자가 모델 자신이므로, 요약 시점에 중요해 보이지 않던 정보(예: "이 파일은 절대 건드리지 말 것"이라는 초반 한 마디)가 탈락할 수 있다. 이 메커니즘을 알면 두 가지 방어를 설계할 수 있다. 첫째, 불변 제약은 대화가 아니라 지시문에 둔다 — 지시문은 압축 대상이 아니라 매 요청 고정 공급되는 것이 일반적이다. 둘째, 긴 작업은 파일을 상태 저장소로 쓴다. 진행 상태·결정·남은 일을 저장소 안의 계획 파일에 쓰게 하면, 컨텍스트가 압축되어도 파일은 손실 없이 남고 새 세션의 인계 문서가 된다.

Hermes가 보여 주는 것: 기계 소비자를 위한 문서 품질의 계량화 ​

Making OpenAPI Documentation Agent-Ready(참고 자료)의 Hermes는 OpenAPI 문서의 스멜 — 누락된 설명, 스키마-구현 불일치, 모호한 타입 — 을 다중 에이전트로 탐지한다. 이 연구의 함의는 API 문서를 넘는다. 문서 품질이 "사람 리뷰어의 감상"이 아니라 기계적으로 점검 가능한 속성의 목록이 될 수 있다는 것이다. 같은 접근을 저장소 지시문에 적용할 수 있다: 지시문의 명령이 실제로 실행되는지 CI에서 검사하고(문서화된 명령의 smoke test), 지시문이 언급하는 경로가 존재하는지 링크 검사하듯 점검한다. 지시문을 계약으로 다룬다는 말의 기술적 완성형은 계약의 자동 검증이다.

정리 ​

  • 컨텍스트 윈도우는 매 루프 전체가 재입력되는 유한 예산이다. 압축은 손실이고 오염은 예산이 남아도 발생하므로, 작업 크기와 세션 길이의 통제가 품질을 직접 결정한다.
  • 정보는 수명에 따라 자리가 다르다: 일회성은 프롬프트, 항상-유효 규칙은 저장소 지시문, 필요-시 배경은 링크된 문서, 학습된 규칙은 메모리 — 그리고 팀 규칙은 메모리가 아니라 지시문에 있어야 한다.
  • 저장소 지시문은 계약이다: PR로 변경하고, 단일 원본을 유지하고, 판정 가능한 문장으로 쓰고, 코드 변경 시 함께 갱신한다.
  • agent-ready 준비의 실체는 상태 소유권, 디자인 토큰, 접근성 기준, 브라우저 지원 범위, API 계약을 찾기 쉬운 파일로 명문화하는 것 — 즉 미뤄 온 온보딩 문서화다.
  • API 문서는 에이전트 소비 기준(드리프트 없음, 필드 의미·단위, 오류 스키마)으로 점검하며, 틀린 메모리와 낡은 지시문은 적극적으로 삭제·갱신한다.

확인 문제 ​

  1. 에이전트가 긴 세션 후반에, 세션 초반에 명시했던 "이 컴포넌트는 서버 컴포넌트로 유지할 것"이라는 제약을 어기고 "use client"를 추가했다. 컨텍스트 동작 모델로 원인 후보를 설명하고, 재발 방지책을 두 가지 이상 제시하라.
정답과 해설

원인 후보: ① 압축 손실 — 세션이 길어져 하네스가 초반 대화를 요약으로 치환했고, 한 번 언급된 제약이 요약에서 탈락했다. ② 오염 — 이후 루프에서 읽은 파일·실패 로그가 쌓이며 초반 제약에 배분되는 주의가 희석됐다. 재발 방지: ① 불변 제약을 대화가 아니라 압축되지 않는 자리로 옮긴다 — 작업 명세의 '변경 금지' 항목, 또는 반복된다면 저장소 지시문의 규칙("서버/클라이언트 경계는 ADR-00N을 따르고 use client 추가는 승인 필요"). ② 세션을 짧게 유지하고, 길어지면 상태·제약을 파일로 인계해 새 세션에서 시작한다. ③ 검증으로 방어 — 경계 위반을 잡는 lint 규칙이나 테스트가 있으면 컨텍스트와 무관하게 걸러진다. 컨텍스트 통제와 기계 검증의 이중 방어가 정석이다.

  1. 팀의 CLAUDE.md가 400줄이다: 코딩 스타일 50줄, React 모범 사례 100줄, 프로젝트 구조 40줄, 명령 10줄, 도메인 규칙 30줄, 과거 장애에서 나온 금지 사항 20줄, 나머지는 일반적 조언이다. 예산 관점에서 이 지시문을 재설계하라.
정답과 해설

기준: 매 세션 고정 지출이므로 "항상 유효 + 이 저장소에서만 참 + 도구로 판정 불가"만 남긴다. 남길 것: 명령 10줄(모든 작업의 검증 기반), 프로젝트 구조 40줄(요약해 더 줄일 수 있음), 도메인 규칙 30줄, 금지 사항 20줄(위반 비용이 커서 가치 최고). 뺄 것: 코딩 스타일 50줄 → 린터·포매터 설정으로 이관하고 "스타일은 pnpm lint가 판정한다" 한 줄로 대체. React 모범 사례 100줄 → 모델이 이미 아는 일반론은 삭제하고, 팀 고유 패턴만 참조 구현 경로("src/features/orders/ 구조를 따른다")로 대체. 일반적 조언 → 삭제. 결과는 100줄 안팎이 되고, 핵심 규칙(금지 사항)이 묻히지 않게 되는 것이 토큰 절약보다 큰 이득이다.

  1. 백엔드 팀이 "우리 OpenAPI 문서는 프론트엔드 개발자들이 잘 쓰고 있는데 왜 에이전트용으로 더 고쳐야 하냐"고 묻는다. 사람 소비와 에이전트 소비의 차이를 근거로 답하고, 우선 점검 항목을 제시하라.
정답과 해설

차이의 핵심: 사람은 문서 밖 채널(팀 지식, 슬랙 질문, 네이밍 관례, 기존 코드 관찰)로 문서의 빈틈을 메우지만, 에이전트는 문서에 적힌 것만 알고 적힌 것을 그대로 믿는다. "잘 쓰고 있다"는 것은 문서가 완전하다는 뜻이 아니라 사람들이 빈틈을 메우는 비용을 지불해 왔다는 뜻이다. 우선 점검 항목(Hermes류 스멜 기준): ① 스키마-실제 응답 드리프트 — 에이전트는 드리프트를 경험으로 보정하지 못하고 틀린 코드를 생성한다. ② 필드의 의미·단위·제약 누락(amount: number의 통화·정밀도). ③ 오류 응답의 상태 코드별 스키마 — 에이전트가 생성하는 오류 처리 품질이 여기 비례한다. ④ enum 전체 목록. 설득 근거로는 에이전트가 이 문서로 클라이언트 코드를 생성하다 실패한 구체 기록을 제시하는 것이 효과적이며, 이 개선은 신규 입사자와 외부 소비자 등 사람에게도 그대로 이득이다.

참고 자료 ​