ICM 아키텍트
폴더 구조가 오케스트레이션을 수행하는 워크스페이스를 구축합니다. 하나의 에이전트가 올바른 파일을 올바른 시점에 읽고, 멀티 에이전트 프레임워크를 대체합니다. 번호가 매겨진 폴더는 순서를 전달하고, 계층 구조는 컨텍스트 범위를 전달하며, 일반 마크다운 파일은 상태를 전달합니다. 인간은 어떤 폴더를 열어도 시스템이 어떤 상태인지 정확히 알 수 있습니다. 상태는 곧 파일이기 때문입니다.
워크스페이스를 도서관이라고 생각해보세요. 라우팅 파일은 카탈로그입니다. 작고 안정적이며 모든 것을 가리키지만 거의 아무것도 저장하지 않습니다. 콘텐츠는 선반(스테이지 폴더, 노드 파일, 참고 자료) 위에 있습니다. 한 명의 사서(한 명의 모델)가 건물을 걸어 다니며, 질문에 따라 어느 선반으로 갈지 결정됩니다. 아무도 도서관 전체를 배낭에 복사하지 않습니다. 그것이 바로 컨텍스트를 채우는(context-stuffing) 행위입니다. 카탈로그는 의도적으로 작게 유지됩니다.
방법: 해석 가능한 컨텍스트 방법론(Interpretable Context Methodology, Van Clief & McDermott, arXiv:2603.16021, MIT 라이선스).
불변의 원칙(Invariants)
모든 ICM은 그 형태와 관계없이 다음 원칙을 따릅니다. 구축하거나 재구성할 때 열 가지를 모두 적용하세요.
- 하나의 폴더, 하나의 역할. 각 폴더는 단일 단계를 수행하거나 단일 종류의 것을 보관하며, 그 목적을 폴더 내부의 파일에 명시합니다. 구조 자체가 문서입니다.
- 작고 안정적인 진입 파일. 루트의
CLAUDE.md(또는AGENTS.md)는 "내가 어디에 있는지, 모든 것이 어디에 있는지, 작업 X를 위해 어디로 가야 하는지"에만 답합니다. 그 외에는 아무것도 하지 않습니다. 약 60줄 미만을 목표로 합니다. 라우팅만 수행하고 콘텐츠는 절대 보관하지 않습니다. - 번호 매기기로 순서 인코딩. 순서가 중요한 경우
01_,02_, ...를 사용합니다. 폴더 이름을 바꾸는 것은 파이프라인의 순서를 재조정하는 것입니다. 이것이 요점입니다. - 모든 폴더 수준 계약은 명시적으로. 각 작업 폴더에
CONTEXT.md를 두어 무엇을 읽는지(입력), 무엇을 하는지(프로세스), 무엇을 쓰는지(출력), 인간이 무엇을 확인하는지를 명시합니다. assets/templates/stage-CONTEXT.md를 참조하세요. - 팩토리 vs. 제품. 참고 자료(규칙, 어조, 스키마, 템플릿 - 실행 간에 안정적)는 작업 산출물(출력물, 초안 - 실행마다 새로 생성)과 구조적으로 분리하여 보관합니다. 팩토리는 한 번 구성하고, 제품은 각 실행이 내보내는 것입니다.
- 모든 출력물은 편집 가능한 표면입니다. 중간 출력물은 인간이 열고, 편집하고, 저장한 후 다음 단계에서 읽을 수 있는 일반 파일입니다. 마지막 출력물을 사람이 읽기 전까지는 아무것도 진행되지 않습니다.
- 단계에 필요한 것만 로드합니다. 단계를 실행하는 에이전트는 계약, 참고 자료, 입력만 읽고 전체 워크스페이스는 읽지 않습니다. 단계당 2,000~8,000 토큰이 적정 범위입니다.
- 일반 텍스트, 링크 가능, 쿼리 가능. 마크다운 + YAML 프론트매터. 링크(
[[위키링크]]또는 상대 경로)는 그래프를 만들고, 프론트매터 레이블은 쿼리를 가능하게 합니다. 사실 하나당 하나의 홈 - 링크가 복사본보다 낫습니다. - 파일시스템이 상태 머신입니다. "상태"는 출력 폴더에 무엇이 존재하는지 스캔하여 도출할 수 있습니다. 생성된 인덱스(파일 맵, 로그)는 스크립트로 재구성하며, 수동 편집하지 않습니다.
- 템플릿 복사로 인스턴스화. 새 작업 단위 = 템플릿 폴더를 복사하는 것이지 빈 페이지에서 시작하는 것이 아닙니다. 템플릿은
_templates/또는_system/폴더에 보관합니다.
모드 선택
- 설명된 프로세스, 아이디어 또는 문제로부터 구축 → 빌드 모드.
- ICM 구조가 필요한 기존 폴더, 저장소, 또는 볼트 → 리스트럭처 모드.
빌드 모드
1. 대화에서 구조 추출하기. 구조는 이미 사람이 작업을 설명하는 방식에 담겨 있습니다. 모양을 강요하지 말고 그들의 구조를 표면화하세요. 한 번에 여러 개가 아닌, 몇 가지씩 질문하세요.
- 반복되는 작업 단위는 무엇인가요? (에피소드, 고객, 보고서, 사람, 팀?)
- 한 번의 실행을 처음부터 끝까지 설명해 주세요. 계속하기 전에 멈춰서 확인하는 지점은 어디인가요?
- 매 실행마다 동일하게 유지되는 것(어조, 규칙, 브랜드, 스키마)과 매 실행마다 새로운 것은 무엇인가요?
- "완료"는 어떻게 생겼나요? 어떤 산출물이 워크스페이스를 떠나나요?
- 이 작업에 관여하는 다른 사람은 누구이며, 그들이 당신에게 묻지 않고 찾아야 하는 것은 무엇인가요?
그들의 멈춤 지점이 스테이지 경계가 됩니다. 그들의 "Y 전에 X를 항상 확인합니다"가 인간 게이트(Human Gate)가 됩니다. 그들의 "항상 Z처럼 들리거나 따라야 합니다"가 팩토리 참고 자료가 됩니다.
2. 형태 선택하기. references/forms.md를 읽고 선택하세요.
| 형태 | 다음과 같을 때 사용하세요 |
|---|---|
| 파이프라인 | 동일한 시퀀스가 반복적으로 실행되어 매번 결과물을 생성할 때 |
| 우산(Umbrella) | 여러 개의 개별 파이프라인이 하나의 브랜드/어조/참조 계층을 공유할 때 |
| 레코드 라이브러리 | 단위가 실행이 아닌 축적되는 레코드(사람, 고객, 세션)일 때 |
| 지식 번들 | 제품이 그 자체로 탐색 가능한 지식(브레인, 위키, 어떤 것의 모델)일 때 |
| 컨텍스트 맵 | 주제가 조직(팀, 프로세스, 데이터 및 그들 간의 연결)일 때 |
실제 워크스페이스는 형태를 혼합합니다(레코드가 미니 지식 번들인 레코드 라이브러리, 파이프라인이 레코드 라이브러리로 출력을 내보내는 경우 등). 자유롭게 구성하세요. 불변의 원칙은 모든 수준에서 재귀적으로 유지됩니다.
3. 작업을 수행하는 가장 작은 구조를 스캐폴딩합니다. assets/templates/에서 스타터를 복사하여 채웁니다. 아직 존재하지 않는 단계, 빈 "기타" 버킷, 또는 추측성 깊이를 위한 폴더를 만들지 마세요. 실제 단계 3개가 상상된 단계 7개보다 낫습니다. 전체 작업이 하나의 저장된 프롬프트에 들어맞는다면 그렇게 말하고 워크스페이스를 전혀 만들지 마세요.
4. 계약을 작성합니다. 루트 CLAUDE.md(식별 + 라우팅 테이블), 루트 CONTEXT.md(파이프라인 또는 스키마 정의), 각 스테이지/허브 폴더당 하나의 CONTEXT.md, 사용자별 팩토리 구성이 필요한 경우 setup/questionnaire.md. 입력은 명시적 파일 경로로 작성하고, 작업(이번 실행)과 참조(모든 실행)로 분할합니다.
5. 워크 테스트로 검증합니다. (아래 참조).
리스트럭처 모드
1. 건드리기 전에 인벤토리를 만듭니다. 트리를 나열합니다. 각 영역에 대해: 무엇인지, 마지막으로 수정한 때, 무엇이 이를 참조하는지 기록합니다. 이 단계에서는 절대 삭제하거나 이동하지 마세요.
2. 숨겨진 형태를 찾습니다. 소유자에게 묻거나(또는 추론하여 확인) 여기서 반복되는 단위는 무엇인지, 작업이 어디서 들어오고 나가는지 질문합니다. 일반적으로 엉망인 상태는 실제 파이프라인, 라이브러리 또는 지도가 골격 없이 성장한 것입니다. 추출하되, 대체하지 마세요. 사람을 인터뷰하듯이 폴더를 인터뷰하세요.
3. 모든 파일을 다섯 가지 역할 중 하나로 분류합니다.
- 카탈로그 - 식별/라우팅 (
CLAUDE.md/ 인덱스 파일이 되거나 이를 제공) - 계약(Contract) - 단계 작동 방식 설명 (
CONTEXT.md가 됨) - 팩토리 - 안정적인 참조 (
_shared/,_system/또는references/로 이동) - 제품 - 실행별 산출물 (스테이지
output/또는 레코드 폴더로 이동) - 죽은(Dead) - 오래되거나, 중복되거나, 대체됨 (
_archive/로 제안, 절대 조용히 삭제하지 않음)
4. 이동하기 전에 제안합니다. 대상 트리와 마이그레이션 맵(이전 경로 → 새 경로 → 역할)을 제시합니다. 승인을 받으세요. 이것은 인간 게이트 위에 구축된 방법론의 인간 게이트입니다. 이를 존중하세요.
5. 마이그레이션합니다. 파일을 이동하고, 진입 파일과 계약을 작성하며, 사실당 하나의 홈(one-home-per-fact) 원칙에 따라 중복을 제거합니다(복사본이 있던 곳에 무언가 참조할 수 있다면 링크를 남깁니다). 방법과 인스턴스를 분리합니다. 구조가 다른 곳에서 재사용된다면 빈 템플릿은 채워진 배포와 별도로 보관합니다.
6. 워크 테스트로 검증합니다.
워크 테스트
기억이 없는 에이전트처럼 냉정하게 워크스페이스를 걸어보며 모든 ICM(신규 또는 재구성)을 검증합니다.
- 루트를 엽니다. 진입 파일과 최대 두 번의 추가 읽기 내에서 "내가 어디에 있는지"와 "현재 작업을 위해 어디로 가야 하는지"에 답할 수 있습니까?
- 아무 스테이지/노드를 선택합니다. 해당 계약이 정확한 입력 경로, 작업, 출력 및 인간 확인 사항을 명시하고 있습니까?
output/폴더(또는 노드 프론트매터)에 무엇이 존재하는지만 스캔하여 파이프라인 상태를 진술할 수 있습니까?- 어떤 라우팅 파일이 콘텐츠 페이로드를 담고 있습니까? 페이로드를 선반으로 옮기고 포인터를 남기세요.
- 어떤 사실이 두 곳에 저장되어 있습니까? 하나를 홈으로 선택하고 다른 곳에서 링크하세요.
- 토큰 확인: 진입 파일 + 하나의 계약 + 해당 입력이 약 2k~8k 토큰 범위에 들어와야 합니다.
단계가 실패하면 더 많이 설명하지 말고, 워크가 작동할 때까지 파일을 이동하거나 분할하여 구조를 수정하세요.
가드레일
- 과도한 구조화를 피하세요. 사다리는 다음과 같습니다: 채팅 → 저장된 프롬프트/스킬 → 폴더 + 하나의 에이전트. 아래 단계가 진정으로 자동화되고 반복될 때만 올라가세요. 두 번 수행한 작업을 위한 워크스페이스는 아키텍처가 아니라 발판(scaffolding)입니다.
- ICM이 한계를 맞는 상황을 인지하세요. 실시간 멀티 에이전트 협업, 높은 동시성의 다중 사용자 서빙, 자동화된 중간 파이프라인 분기에는 실제로 프레임워크 코드가 필요합니다. ICM은 순차적이고 인간이 검토하며 반복적인 작업(대부분의 지식 작업에 해당하지만 전부는 아님)을 위한 것입니다.
- 실제에서 발견된 안티패턴: 표류하는 중복 진입 파일(하나를 다른 파일에서 생성하거나 하나를 포인터로 만들 것); 실제 파일이 더 이상 사용하지 않는 이름을 강제하는 스키마 문서(스키마 또는 파일 중 하나를 업데이트할 것); 생성된 인덱스에 대한 수동 편집; 구조화된 데이터 대신 슬라이드를 생성하는 워크샵 세션(모든 작업 세션은 구조가 보유할 수 있는 산출물로 끝나야 함); 하향식으로 선언된 패턴(한 팀의 불평은 불만일 뿐, 세 번 독립적으로 나타난 동일한 형태는 구조임).
참고 자료
- references/core.md — 다섯 가지 디자인 원칙, 다섯 계층 컨텍스트 계층 구조, 명명 규칙, 토큰 규율. 계약을 작성하거나 구조적 결정에 이의가 있을 때 읽으세요.
- references/forms.md — 다섯 가지 형태에 대한 심층 설명: 골격 트리, 정의 동작, 실패 모드. 빌드 모드 2단계 또는 리스트럭처 모드 2단계에서 읽으세요.
- assets/templates/ — 복사 가능한 스타터:
CLAUDE.md, 워크스페이스CONTEXT.md,stage-CONTEXT.md,node.md,schema.md,questionnaire.md.