docs-architect

Docs Architect — AI-Optimized Documentation (v2)

Build and maintain documentation that rides on Claude Code's native loading mechanisms. Cuts AI token consumption by 20–40% versus the v1 custom-summary pattern while preserving all information and giving humans a clean reference.

Core principle

Docs are a knowledge base. The AI receives only what is strictly necessary per task. v2 uses the official .claude/rules/ mechanism with two loading modes:

• Always-loaded rules — frontmatter-less .claude/rules/*.md files load at session start alongside CLAUDE.md. Use for universally-needed content (business, stack, conventions, core architecture).
• Path-scoped rules — .claude/rules/*.md with paths: frontmatter auto-load only when Claude reads matching files. Zero startup token cost. Use for subsystem-specific rules (backend, frontend, api, database, testing).

Full human docs live in docs/*.md as the source of truth. .claude/rules/*.md are lean (≤40 lines, ≤12 bullets) distillations mirrored from the full docs.

Architecture

./CLAUDE.md                            # <100 lines — hard NOs + pointer to rules
./.claude/rules/                       # AI-facing rules (flat, no subfolders)
  ├── business-context.md              # always-loaded
  ├── coding-rules.md                  # always-loaded
  ├── tech-stack.md                    # always-loaded
  ├── architecture.md                  # always-loaded
  ├── backend.md                       # path-scoped: backend/**
  ├── frontend.md                      # path-scoped: frontend/**
  ├── api.md                           # path-scoped: **/Controllers/**, **/routes/**
  ├── database.md                      # path-scoped: **/Entities/**, **/migrations/**
  └── testing.md                       # path-scoped: **/*.test.*, **/tests/**
./.claude/agents/doc-explorer.md       # research subagent (isolated context)
./.claude/commands/                    # /docs-audit, /docs-sync, /docs-migrate
./docs/                                # full human-readable reference
  ├── README.md                        # governance + index
  ├── architecture.md                  # full architecture doc
  ├── coding-rules.md                  # full conventions
  ├── tech-stack.md                    # full package catalog
  ├── api-contracts.md                 # full endpoint catalog
  ├── database-schema.md               # full table catalog
  ├── deployment.md                    # full dev/prod reference
  ├── roadmap.md                       # product phases, KPIs, decisions
  ├── backlog.md                       # story registry
  ├── bugs.md                          # bug registry
  ├── ideas.md                         # raw ideas inbox
  ├── stories/ bugs/ plans/            # individual item files
  └── research/                        # deep reference docs