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:

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

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

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

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 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.