Update Docs

Update Project Documentation

Two responsibilities:

1. CLAUDE.md — concise project overview (always loaded)
2. .llmdocs/ — detailed per-concept docs (loaded on demand)

1. CLAUDE.md — The Map

Gather Context

• Read current CLAUDE.md (if exists)
• Explore codebase: directories, config files, key modules
• Review conversation history to identify what changed this session

Write/Update CLAUDE.md

Target: under 150 lines. Every line must earn its place.

# <Project Name>

<1-2 line purpose>

## Stack
<bullet list: language, frameworks, key deps>

## Architecture
<key dirs and what they contain>

## Commands
<build, test, lint, deploy — commands only>

## Conventions
<style, naming, patterns — only what prevents mistakes>

## Key Concepts
<domain terms, business logic Claude must know>

## Docs
Detailed docs in `.llmdocs/`:
- `architecture.md` — <1-line description>
- `data-model.md` — <1-line description>

CLAUDE.md Rules

• NO verbose explanations — Claude infers
• NO duplicating .llmdocs/ content — just reference with short description
• The ## Docs section MUST list all .llmdocs/ files with a 1-line description each
• Preserve existing custom instructions (git workflow, env vars, etc.)
• Ask before removing any existing content
• Use @.llmdocs/filename.md import if a doc should always be loaded

2. .llmdocs/ — The Territory

Process

1. Assess: review what was done this session (conversation history, git diff)
2. Identify: determine which existing docs are affected, or if a new doc is needed
3. Propose: tell the user which docs you plan to update/create and what changes
4. Validate: get user approval before writing
5. Update CLAUDE.md: ensure the ## Docs section lists any new doc files

If nothing changed that warrants doc updates, say so and move on.

Location

Use the path specified in existing CLAUDE.md, or default .llmdocs/ at project root.

Structure

Flat, 1 file per concept:

.llmdocs/
  architecture.md    # Components, interactions, data flow
  api.md             # Endpoints, request/response
  data-model.md      # Schema, models, relationships
  deployment.md      # Deploy process, environments
  <concept>.md       # Domain-specific as needed

Doc File Format

# <Concept>

<1-line purpose>

## <Section>
<content: headers, tables, code blocks — no prose paragraphs>

.llmdocs/ Rules

• Max 200 lines per file — split if larger
• Include file paths with line refs where useful (src/auth/login.ts:42)
• Update existing docs incrementally, don't rewrite from scratch
• If a doc is accurate and unaffected by recent changes, don't touch it
• Accuracy over coverage: only document what's verifiable from code

3. Summary Output

After running, output:

• Files created/modified
• CLAUDE.md changes (sections added/updated/removed)
• Docs updated/created (or "no doc changes needed")