claude-docs-init

name	claude-docs-init
description	Initialize .claude/docs/ and CLAUDE.md for a repository. Analyzes the codebase and creates agent-optimized documentation so Claude Code can navigate, modify, and test the project effectively.

Claude Docs Init

Create .claude/docs/ files and a CLAUDE.md that give future agent sessions the context they need to work effectively in this repository. All output is agent-optimized: terse, unambiguous, machine-parseable.

Workflow

1. Analyze the repository

Read the project root to determine:

• Language/ecosystem (Go module, npm package, Python project, Rust crate, etc.)
• Build system (go build, make, npm, cargo, etc.)
• Project structure (monorepo, single package, multi-package, CLI + library, etc.)
• Test framework (go test, jest, pytest, cargo test, etc.)
• CI/CD (.github/workflows, Makefile targets, etc.)
• Existing docs (README, CONTRIBUTING, existing CLAUDE.md)

2. Generate core docs (all projects)

These docs apply to every repository regardless of language:

Doc	Content
packages.md	Package/module map: purpose, public API (key functions/types with signatures), key files. One section per package/module.
testing.md	Test data layout, test helpers, how to run tests, golden file patterns, env vars, skip maps, CI commands.
dependencies.md	Internal dependency graph between packages/modules. Arrows show import direction. Layer grouping (leaf → core → processing → application).

3. Generate ecosystem-specific docs

Based on language/ecosystem detected in step 1, generate additional docs from the applicable section below.

4. Generate CLAUDE.md

Create CLAUDE.md at project root with:

1. One-line project description
2. Pre-Read Rules table — maps triggers to doc files. Every doc from steps 2-3 must appear.
3. Cache Maintenance section — rules for keeping docs in sync + table mapping each doc to its update trigger.

5. Present summary

Show the user what was created and ask them to review.

---

Ecosystem: Go Module

Detect: go.mod in project root.

Additional analysis

• Run go list ./... to enumerate packages.
• For each package, read exported symbols via source (or go doc ./pkg).
• Check for cmd/ directories (CLI tools).
• Check for internal/ packages.
• Check for golden test patterns (testdata/, .expected, .golden files).
• Check for build tags, generate directives.

Additional docs

Doc	Content	When
error-formatting.md	Error types, format strings, error wrapping patterns, ErrorHandler interfaces.	Project defines custom error types or formatting.
cli.md	CLI flags, subcommands, pipeline, exit codes.	Project has cmd/ or main.go CLI entry points.
internals.md	Core data structures, state machines, processing pipelines.	Project has complex internal architecture (parser, compiler, runtime, etc.).
data-model.md	Key types, struct hierarchies, interface contracts, node/object graphs.	Project defines a rich type hierarchy (DOM, AST, IR, etc.).
validation.md	Compile→validate flow, schema data model, error reporting.	Project implements schema/validation logic.
parity.md	Feature status vs reference implementation, test counts, known gaps, limitations.	Project reimplements or ports another system.

packages.md format (Go)

For each package:

## pkgname/

One-line purpose.

- **FuncName(params) → (returns)** — description
- Key types: `Type1`, `Type2`
- Options/config: `WithX()`, `WithY()`
- Files: `file1.go`, `file2.go`
- Imports: pkg1, pkg2

Rules:

• Include error in return signatures when present.
• List only public API. Skip unexported helpers.
• Group related functions (e.g., Parse/ParseReader/ParseFile together).
• For large packages, focus on entry points and key types — not every exported function.

testing.md format (Go)

Include:

• Test package naming convention (xxx_test vs xxx).
• Test data directory layout (tree diagram).
• Golden file naming/extensions.
• Common test helpers with signatures and purpose.
• Environment variable filters for running test subsets.
• Build tags used in CI.
• How to run: go test ./..., specific flags, race detector.

dependencies.md format (Go)

pkg → dep1, dep2
  → transitive (via dep1)

Then group by layer:

• Leaf packages (no internal deps)
• Core layer
• Processing layer (depends on core)
• Composition layer (depends on processing)
• Application layer (cmd/, main)

---

Ecosystem: Node.js / TypeScript

Detect: package.json in project root.

Additional analysis

• Read package.json for scripts, dependencies, workspaces.
• Check for tsconfig.json (TypeScript).
• Check for monorepo tools (lerna, nx, turborepo).
• Enumerate exports from index.ts/index.js or package.json exports field.

Additional docs

Doc	Content	When
api.md	REST/GraphQL endpoint map, request/response types, auth.	Project is a web server or API.
components.md	Component tree, props interfaces, state management.	Project is a React/Vue/Svelte app.
config.md	Environment variables, config files, feature flags.	Project has significant runtime configuration.

packages.md format (Node.js)

For each package/workspace:

## package-name

One-line purpose.

- **export function funcName(params): ReturnType** — description
- Key types: `Interface1`, `Type2`
- Entry: `src/index.ts`
- Files: `src/router.ts`, `src/middleware.ts`

---

Ecosystem: Python

Detect: pyproject.toml, setup.py, or setup.cfg in project root.

Additional analysis

• Read pyproject.toml for project metadata, dependencies, entry points.
• Check for src/ layout vs flat layout.
• Check for type hints (py.typed, *.pyi stubs).
• Enumerate modules via directory structure.

Additional docs

Doc	Content	When
api.md	Endpoint map, serializers, auth.	Django/Flask/FastAPI project.
cli.md	CLI commands, arguments, entry points.	Click/argparse/typer CLI.
config.md	Settings, environment variables, config hierarchy.	Project uses settings module or env vars.

---

Ecosystem: Rust

Detect: Cargo.toml in project root.

Additional analysis

• Read Cargo.toml for workspace members, features, dependencies.
• Check for src/lib.rs vs src/main.rs.
• Enumerate public API via pub exports.

Additional docs

Doc	Content	When
unsafe.md	Unsafe blocks, FFI boundaries, safety invariants.	Project uses unsafe.
features.md	Cargo features, conditional compilation, feature gates.	Project has non-trivial feature flags.

---

Doc Authoring Rules

All docs MUST follow these rules:

• Optimize for agent/LLM consumption, not human readability.
• Terse, imperative, unambiguous. No filler, hedging, or politeness.
• Use → for cause/effect. Use NEVER/ALWAYS/MUST for hard rules.
• Prefer tables and bullet lists over prose.
• One rule per bullet. No compound sentences joining unrelated rules.
• Omit articles (a, an, the) where meaning is clear.
• No redundant examples — one example per pattern is enough.
• No motivational text. State rules only.
• Commands/paths in backticks.

CLAUDE.md Format

<!-- Agent-consumed file. Keep terse, unambiguous, machine-parseable. -->

# Project Name

One-line description.

## Pre-Read Rules

Read the linked doc BEFORE working in that area. No exceptions.

| Trigger | Doc |
|---------|-----|
| {trigger description} | `.claude/docs/{file}.md` |
...

## Cache Maintenance

These docs cache repository state. Still read source before modifying code.

1. When your changes affect a doc below, update it in the same commit.
2. If you notice any doc is wrong or stale — even on an unrelated task — fix it immediately.

| Doc | Update trigger |
|-----|----------------|
| `{file}.md` | {what changes require updating this doc} |
...

Rules

• NEVER overwrite an existing CLAUDE.md without showing the user a diff first.
• If CLAUDE.md already exists, merge new pre-read rules and cache maintenance entries into it.
• Read actual source code to populate docs — do not guess or hallucinate APIs.
• For large projects (>50 packages), focus on the most important packages and note "see source for full list" for the rest.
• Each doc file should be self-contained. No cross-references between docs except in CLAUDE.md's pre-read table.
• Keep individual doc files under 300 lines. Split if larger.