dotdotgod는 문서 목차(Table of Contents)를 한 번 만들고 방치하지 않습니다. 초기화(initialization), README 인덱스, 자동화된 검증(automated validation), 추적 가능성(traceability), 영향 분석(impact analysis), 그리고 아카이빙(archiving)을 일반적인 개발 워크플로우(workflow)와 결합합니다. 따라서 문서가 추가, 이동, 분할 또는 완료됨에 따라 내비게이션 구조를 최신 상태로 유지할 수 있습니다.

이전 글에서는 프로젝트 디렉토리와 파일 이름을 AI 에이전트(AI agents)를 위한 책과 같은 목차로 설명했습니다. 하지만 프로젝트가 성장함에 따라 해당 구조는 여전히 퇴보할 수 있습니다. 즉, 새로운 문서가 README 인덱스에서 사라지거나, 링크가 계속해서 오래된 경로를 가리키거나, 완료된 계획이 진행 중인 작업과 섞여 있는 등의 문제가 발생할 수 있습니다.

dotdotgod는 문서 구조를 단순한 권장 사항 이상으로 취급합니다. 문서가 생성, 변경 또는 완료되는 모든 단계에 유지보수 메커니즘을 배치합니다.

초기 인덱스를 생성한 후 프로젝트와 함께 확장하기

dotdotgod는 프로젝트 초기화(initialization) 단계에서 기준이 되는 문서 구조를 생성합니다.

AGENTS.md
CLAUDE.md
CODEX.md
...

이것들은 빈 디렉토리가 아닙니다. 각 README는 해당 영역의 역할과 문서를 배치하는 규칙을 설명합니다. 프로젝트는 개별 장(chapter)이 작성되기 전에 책의 주요 부분과 그에 따른 초기 목차를 가지고 시작합니다.

서로 다른 에이전트(agents)들이 동일한 구조를 사용합니다. AGENTS.md는 공유된 작업 규칙을 제공하며, CLAUDE.md와 CODEX.md는 해당 규칙으로 들어가는 가벼운 진입점(entry points) 역할을 합니다. 문서 탐색(documentation discovery)은 docs/README.md에서 시작되므로, Pi, Claude Code, Codex가 별도의 문서 시스템을 만드는 대신 경로와 용어를 공유할 수 있습니다.

dotdotgod는 모든 문서를 하나의 거대한 인덱스에 나열하지 않습니다. 각 디렉토리의 README.md가 해당 영역의 로컬 목차(local table of contents) 역할을 합니다.

docs/README.md
    ↓
docs/spec/README.md
...

각 README는 중요한 문서, 하위 디렉토리, 상태, 그리고 한 줄로 된 목적을 기록합니다. 문서를 추가, 이름 변경, 분할 또는 아카이빙할 때도 동일한 변경 사항 내에서 가장 가까운 README를 업데이트해야 합니다. 따라서 README는 단순한 소개글이 아니라, 능동적인 라우팅 테이블 (routing table) 역할을 합니다.

작은 주제는 하나의 집중된 문서로 시작합니다.

docs/spec/PAYMENT.md

도메인이 성장하면, 자체적인 README와 지원 문서들을 갖춘 디렉토리로 승격될 수 있습니다.

docs/spec/payment/
├── README.md
├── LIST_API.md
...

이렇게 함으로써 하나의 인덱스 (index)가 너무 길어지는 것을 방지하고, 하나의 커다란 문서에 관련 없는 책임들이 쌓이는 것을 막을 수 있습니다. 문서화 (documentation)가 성장함에 따라, 탐색 계층 구조 (navigation hierarchy)도 함께 성장합니다.

구조를 확장한 후, 프로젝트는 각 경로의 메모리 역할 (memory role)을 구성할 수 있습니다. dotdotgod config . 명령은 해결된 정책을 보여주며, dotdotgod config init . 명령은 편집 가능한 기본값들을 dotdotgod.config.json에 작성합니다.

{
  "memory": {
    "areas": [
...

프로젝트는 추가 경로를 등록하거나, 기본 spec, architecture, test 영역의 경로와 우선순위를 변경하거나, 필요하지 않은 영역을 제거할 수 있습니다. 이 구성은 파일을 생성하거나 삭제하지 않습니다. 대신 기존 문서들을 메모리 역할과 범위 (scope)에 따라 분류합니다. Memory Area Config specification에서 필드와 우선순위 규칙을 정의합니다.

이름 및 구조 자동 검증

문서화 규칙이 저자의 규율에만 의존한다면 오래 지속되기 어렵습니다. dotdotgod CLI는 프로젝트 문서가 구성된 구조를 따르는지 확인합니다.

dotdotgod validate . \
  --include-local-memory \
  --check-index

검증 (Validation) 과정에서는 다음 사항을 확인합니다:

• 필수 베이스라인 문서 및 README 인덱스 존재 여부
• 마크다운 (Markdown) 링크 및 구조화된 추적 가능성 (traceability) 데이터의 유효성
• 문서 이름, 경로 및 크기가 프로젝트 규칙을 따르는지 여부
• 인덱스가 현재 파일들과 일치하는지 여부

문서 크기 또한 목차 (Table of Contents)를 유지하는 데 중요한 부분입니다. 하나의 Markdown 파일에 대한 기본 제한은 200행 및 10,000자입니다. 이 중 어느 한 제한이라도 초과하면 FILE_TOO_LONG 또는 FILE_TOO_LARGE가 보고됩니다. 하나의 문서를 무한정 확장하는 대신, 주제별로 분할하고 가장 가까운 README 인덱스를 업데이트하십시오.

프로젝트는 dotdotgod.config.json에서 크기 제한과 제외 경로를 조정할 수 있습니다.

{
  "validation": {
    "markdown": {
...

제외 대상은 범위를 좁게 유지해야 하며, 의도적으로 크게 만든 인덱스나 생성된 문서와 같이 분할하기 어려운 파일만 포함해야 합니다. 일회성 검증은 --max-lines 및 --max-chars를 사용하여 제한을 무시할 수 있습니다. 생성된 추적성 링크 (traceability-link) 섹션과 json dotdotgod 블록은 크기 측정에서 제외되므로, 생성된 메타데이터가 문서 본문의 크기를 왜곡하지 않습니다.

이는 출판 전 책을 교정하는 것과 유사합니다. 목차, 상호 참조 (cross-references), 누락된 페이지를 확인하는 과정입니다. 자동화된 검증은 탐색 구조가 무너지기 전에 누락되거나 크기가 너무 큰 항목을 찾아냅니다.

사양(Specs), 구현(Implementation), 그리고 테스트(Tests) 연결하기

잘 구조화된 인덱스라 할지라도 문서가 코드와 동떨어지게 되면 신뢰를 잃게 됩니다. dotdotgod는 중요한 동작 사양 (behavior specifications)에 대해 구조화된 추적성 (traceability)을 기록하여, 이를 구현 파일, 테스트, 관련 문서 및 검증 명령과 연결할 수 있습니다.

예를 들어, CLI 구현을 변경한 후 graph impact를 사용하면 검토가 필요한 사양과 테스트를 식별할 수 있습니다.

dotdotgod graph impact . --changed <path>

그래프와 인덱스는 원본 문서를 대체하지 않습니다. 후속 기사인 변경 검토에 포함되어야 할 문서를 찾는 방법에서는 변경된 파일이 어떻게 관련 문서로 이어지는지, 그리고 그 결과가 어떻게 순위가 매겨지는지 설명합니다.

현재 계획과 과거 기록의 분리

문서가 오래될수록 현재 정보와 과거 정보 사이의 구분이 더욱 중요해집니다. 진행 중인 작업은 다음 위치에 존재합니다:

docs/plan/<task-slug>/README.md

계획 (plan)은 목표, 범위 (scope), 대상 파일, 리스크 (risks), 구현 순서 (implementation sequence), 검증 (verification), 그리고 현재 상태를 기록합니다. 작업이 완료되면, 계획은 다음 위치로 이동합니다:

docs/archive/plan/<task-slug>/

docs/archive/README.md는 완료된 작업에 대한 역사적 인덱스 (historical index)로 유지됩니다. 이력은 현재 작업 큐 (work queue)와 섞이지 않고 보존됩니다.

에이전트 (Agents)는 기본적으로 모든 아카이브 본문을 로드하지 않습니다. 에이전트는 먼저 역사적 인덱스를 조사하며, 과거의 결정이 관련이 있는 경우에만 특정 기록을 엽니다. 아카이빙 (Archiving)은 완료된 작업을 활성 목차 (table of contents)에서 제거하면서도 이력을 보존합니다.

워크플로 (Workflow)에 의해 유지되는 목차

dotdotgod는 초기화와 공유된 에이전트 규칙을 통해 기준 인덱스 (baseline index)를 생성한 다음, 각 README를 로컬 인덱스로 사용합니다. 문서가 늘어남에 따라 도메인 (domains)은 디렉토리 (directories)로 승격됩니다. 검증 (Validation) 및 영향 분석 (impact analysis)은 링크와 추적성 (traceability)을 확인하며, 계획 수명 주기 (plan lifecycle)는 현재의 의도와 역사적 기록을 분리합니다. 이후 로드 (Load)는 유지 관리된 인덱스를 선택적 읽기를 위한 프로젝트 메모리 맵 (project-memory map)으로 사용할 수 있습니다.

문서화 시스템이 유용하게 유지되는 이유는 초기 구조가 깔끔했기 때문이 아닙니다. 문서를 추가, 변경, 분할 또는 완료하는 모든 작업에는 목차를 업데이트하기 위한 규칙도 필요합니다.

dotdotgod는 단순히 마크다운 (Markdown) 파일 더미를 유지하려는 것이 아닙니다. dotdotgod는 사람과 여러 AI 에이전트가 동일한 방식으로 읽고, 변경하고, 검증할 수 있는 **살아있는 프로젝트 메모리 시스템 (living project-memory system)**을 유지합니다.

추가 읽기

추가 읽기

• AI Agent Memory Starts with a Documentation Table of Contents
• Load Project specification
• Markdown validation configuration
• Graph impact command specification
• Impact ranking architecture
• Documentation structure architecture