02-구조

02. 구조 — 좋은 트리의 6가지 특징

1. 최상위는 권한·역할 단위로

• src/, tests/, docs/ — 단순 코드 프로젝트.
• wiki/, sources/, .omc/, PRD/ — 본 위키처럼 다중 라이프사이클이 섞일 때.
• 권한·자동화 규칙이 폴더 경계를 따른다(wiki/** 직접 쓰기 OK, sources/** frontmatter만 등).

2. 이름이 의도를 말한다

• ❌ misc/, temp/, archive/, notes_v3_FINAL/
• ✅ cases/by-pattern/, cases/by-role/, agent_docs/migration/

3. 약속된 파일이 루트에

긴 에이전트가 항상 첫 번째로 보는 파일들 — CLAUDE.md, AGENTS.md, README.md, claude-progress.txt, init.sh — 은 최상위에 둔다. 검색 비용 0.

4. 점진적 공개를 트리로 표현

• 매 턴 들어가는 핵심: 루트 CLAUDE.md (≤300줄).
• 가끔 필요한 전문 지침: agent_docs/security.md, agent_docs/release.md.
• 모델이 이름만으로 어디를 봐야 할지 추측 가능해야 한다.

5. 사례·예제는 다중 분류

본 위키는 사례를 by-pattern, by-role, by-tool 세 곳에 동시에 등록한다. 모델이 어느 각도에서 들어와도 찾을 수 있다.

6. 상태 디렉터리는 따로

실행 상태(.omc/state/), 노트(.omc/notepad.md), 메모리(.omc/project-memory.json)는 별도 최상위 폴더 에 모은다. 사람은 무시해도 되고, 자동화는 한 곳만 본다(Part 3/06).

Subagent의 컨텍스트 격리

Claude Code Subagent docs가 명시한다.

“Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.”

의역: “각 서브에이전트는 자체 시스템 프롬프트, 특정 도구 접근, 독립 권한을 가진 자기만의 컨텍스트 윈도우에서 실행된다.”

서브에이전트별 정의 파일(.claude/agents/<name>.md 같은)도 트리의 일부다. 트리가 곧 멀티 에이전트의 라우팅 표.

”디렉터리 트리 = 사이트맵”

실제로 Karpathy의 llm-wiki 패턴을 따르는 본 위키는 wiki/SITEMAP.md를 두고 트리를 글로 한 번 더 표현한다. 사람이 grep으로 찾기도, 모델이 인용하기도 쉽다.