---
name: scaffold-claude-index
description: Create or refresh lightweight CLAUDE.md index files for the repository root and for substantial logic-bearing subdirectories. Use when bootstrapping Claude Code memory for a repo, reducing exploration cost, or documenting architecture without bloating CLAUDE.md.
disable-model-invocation: true
argument-hint: [optional-path]
allowed-tools:
  - Read
  - Write
  - Edit
  - MultiEdit
  - Glob
  - Grep
  - LS
  - Bash(find *)
  - Bash(rg *)
  - Bash(git ls-files *)
  - Bash(tree *)
effort: high
---

# Scaffold lightweight CLAUDE.md indexes

Create or refresh lightweight `CLAUDE.md` files that act as thin indexes, not long documentation dumps.

If `$ARGUMENTS` is present, treat it as the target root path. Otherwise use the current repository root.

## Goal

Produce:
1. one root `CLAUDE.md` for the project,
2. additional `CLAUDE.md` files in subdirectories that contain substantial logic,
3. concise files that help future Claude sessions navigate the codebase quickly without reading the entire repository.

The result must improve navigation and adherence while keeping context cost low.

## Non-negotiable rules

- Keep every generated `CLAUDE.md` concise, high-signal, and specific.
- Prefer bullets over prose.
- Do not create file-by-file inventories.
- Do not paste large code snippets.
- Do not copy README/package manifests verbatim.
- Do not include information Claude can trivially infer from reading one obvious file.
- Do not include volatile details that will go stale quickly unless they are operationally critical.
- Do not exceed 200 lines in any `CLAUDE.md`. Aim well below that.
- Prefer updating existing `CLAUDE.md` files instead of replacing them wholesale.
- Preserve clearly human-authored custom notes unless they are obviously stale or contradictory.
- If two scopes conflict, the more local `CLAUDE.md` should state that it overrides broader guidance for its subtree.

## What qualifies as a “substantial logic” directory

Create a local `CLAUDE.md` only for directories that carry meaningful behavior or decision-making logic.

Strong candidates:
- `src`, `app`, `packages/*`, `services/*`, `libs/*`, `modules/*`
- backend or frontend app roots
- API layers
- domain or business-logic layers
- workers, jobs, schedulers, pipelines
- adapters, integrations, SDK wrappers
- significant test harnesses if they contain real architecture or custom utilities

Usually skip:
- `node_modules`, `.git`, `dist`, `build`, `out`, `coverage`, `.next`, `.venv`, `vendor`
- generated code
- asset-only folders
- trivial config-only folders
- folders with only one or two obvious files and no architectural value

Heuristics:
- create a local `CLAUDE.md` when a directory is a clear architectural boundary, or
- when it has enough internal complexity that future work there would benefit from local guidance, or
- when it has conventions / entry points / gotchas that are not obvious from the parent index

## Discovery process

Before writing anything, inspect the repository efficiently.

Read high-signal sources first:
- root README and docs index if present
- package/workspace manifests
- build/test runner files
- container/dev environment files
- top-level source directories
- key entrypoints and routing/bootstrap files
- monorepo workspace config if present

Use fast discovery first, deep reads second:
1. identify tech stack and workspace shape,
2. identify top-level apps/packages/modules,
3. identify main runtime entrypoints,
4. identify test/build/lint commands,
5. identify project-specific conventions and sharp edges,
6. decide which subdirectories deserve their own local index.

Only read deeper when needed to remove ambiguity.

## Writing the root CLAUDE.md

The root file should be a project-wide index.

Use this structure, adapting as needed:

# Project Index

## Purpose
- what this repository does
- the main product/system boundaries

## Stack
- major languages, frameworks, package/build systems, deployment surface

## Commands
- the few most important commands Claude should know for build, test, lint, run, typecheck, and repo-wide verification
- only include commands that are real and project-specific

## Architecture Map
- top-level directories and what responsibility each owns
- keep each entry to one short bullet

## Entry Points
- primary app/service/package entrypoints
- bootstrap files, routing roots, job runners, or API roots

## Change Guidance
- repo-wide conventions Claude should follow
- where to add new code
- what not to touch casually
- verification expectations before considering work done

## Subtree Guides
- relative links to nested `CLAUDE.md` files that were created
- one-line description for each subtree

## Sharp Edges
- non-obvious gotchas, important invariants, or risky areas

The root file must stay broad. It should point Claude to the right place, not explain every subsystem in detail.

## Writing nested CLAUDE.md files

For each selected substantial directory, create a local thin index focused only on that subtree.

Use this structure, adapting as needed:

# <subtree> Index

## Responsibility
- what this subtree owns
- what it explicitly does not own, if useful

## Read First
- the few files or subfolders a future Claude session should inspect first

## Local Structure
- short bullets for important internal components/modules

## Entry Points / Flow
- request flow, job flow, event flow, render flow, or data flow as relevant

## Dependencies
- main inbound callers / upstreams
- main outbound integrations / downstreams

## Local Conventions
- patterns specific to this subtree
- naming rules, layering rules, file placement rules, testing expectations

## Sharp Edges
- pitfalls, invariants, migration traps, side effects, hidden coupling

Keep subtree files highly local.
Do not restate root-level information unless necessary for safe local work.

## Update behavior

If a `CLAUDE.md` already exists:
- preserve valuable existing guidance,
- remove obvious duplication,
- tighten vague wording,
- split broad versus local guidance correctly,
- keep the most important instructions near the top.

If a file is too large:
- compress it aggressively,
- convert verbose prose into bullets,
- move broad material upward to the root file,
- keep only subtree-relevant instructions locally.

## Quality bar

A good result lets a future Claude session answer all of these quickly:
- What is this repo/subtree for?
- Where should I start reading?
- Where should new code probably go?
- What commands verify my change?
- What are the hidden traps here?

If a section does not help answer one of those questions, cut it.

## Final output to the user

After writing files, report:
1. which `CLAUDE.md` files were created or updated,
2. why each chosen subdirectory qualified,
3. any directories you intentionally skipped,
4. any ambiguous areas where the codebase lacked enough signal,
5. the top 3 recommendations for future improvement if the user wants even better Claude navigation.

When unsure, bias toward fewer, better `CLAUDE.md` files rather than many shallow ones.