02-구조

02. 구조 — CLAUDE.md와 AGENTS.md의 절(切)들

HumanLayer는 CLAUDE.md가 다뤄야 할 것을 세 카테고리로 정리한다.

카테고리	내용
WHAT	기술 스택, 프로젝트 구조, 모노레포 아키텍처
WHY	프로젝트의 목적과 각 컴포넌트의 역할
HOW	개발 워크플로우, 테스트 절차, 빌드 명령

점진적 공개(Progressive Disclosure)

핵심 디렉티브는 CLAUDE.md에 두고, 전문화된 가이드는 agent_docs/... 같은 별도 마크다운에 두고 파일 참조 로 연결한다. 매 턴 컨텍스트에 들어가는 토큰을 줄이면서도 필요할 때 모델이 가져갈 수 있게 한다.

“Store specialized guidance in separate markdown files with file references.”

의역: “전문 지침은 별도 마크다운 파일에 두고 파일 참조로 연결하라.”

길이 권장치

• 300줄 미만 — 일반 권장치.
• 60줄에 가깝게 — HumanLayer 자체 루트 파일.
• 150~200 지시문 이내 — 프론티어 모델 한계 내.

OMC AGENTS.md의 스키마 계약

OMC는 가이던스 스키마를 표준화한다.

절	매핑
Role & Intent	제목 + 첫 단락
Operating Principles	<operating_principles>
Execution Protocol	delegation/model routing/agent catalog/skills/team pipeline
Constraints & Safety	keyword detection, cancellation, state-management
Verification & Completion	<verification> + <execution_protocols>의 continuation
Recovery & Lifecycle Overlays	<!-- OMX:RUNTIME:START --> 마커로 런타임 훅이 덧붙임

마커 경계(<!-- OMX:RUNTIME:START --> ... <!-- OMX:RUNTIME:END -->)는 안정적·비파괴적이어야 한다. 런타임이 덮어쓰는 동안 사람이 손으로 쓴 내용을 보존하기 위함.

CLAUDE.md vs AGENTS.md

	CLAUDE.md	AGENTS.md
주체	Claude Code 공식 메모리	OMC / 멀티 에이전트 오케스트레이션 표준
대상	단일 에이전트 행동	위임·라우팅·팀 파이프라인
추천 길이	≤300줄	더 길어도 무방 (스키마 절 단위)
자동 주입	매 대화에 자동	Codex/Cursor/OMC 등 다른 하네스가 함께 사용

두 파일을 같이 두는 게 베스트 프랙티스로 굳어지고 있다. 같은 사실을 두 번 쓰지 말고, 각자 책임을 분리한다.