---
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/refresh `CLAUDE.md` files as thin indexes, not doc dumps.

If `$ARGUMENTS` present, use as target root. Else current repo root.

## Goal

Produce:
1. one root `CLAUDE.md`,
2. `CLAUDE.md` in subdirs with substantial logic,
3. concise files for fast navigation without reading whole repo.

Result must improve navigation + adherence, keep context cost low.

## Non-negotiable rules

- Concise, high-signal, specific.
- Bullets over prose.
- No file-by-file inventories.
- No large code snippets.
- No verbatim README/manifest copies.
- Skip trivially inferable info.
- Skip volatile details unless operationally critical.
- Max 200 lines per `CLAUDE.md`. Aim lower.
- Update existing files, don't replace wholesale.
- Preserve human-authored notes unless stale/contradictory.
- Conflicting scopes: local file states override of broader guidance.

## What qualifies as a "substantial logic" directory

Local `CLAUDE.md` only for dirs with meaningful behavior/decision logic.

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

Skip:
- `node_modules`, `.git`, `dist`, `build`, `out`, `coverage`, `.next`, `.venv`, `vendor`
- generated code
- asset-only folders
- trivial config-only folders
- folders with 1-2 obvious files, no architectural value

Heuristics — create local `CLAUDE.md` when:
- clear architectural boundary, or
- enough complexity future work benefits from local guidance, or
- conventions/entrypoints/gotchas not obvious from parent.

## Discovery process

Inspect repo efficiently before writing.

Read high-signal first:
- root README, docs index
- package/workspace manifests
- build/test runner files
- container/dev env files
- top-level source dirs
- key entrypoints, routing/bootstrap files
- monorepo workspace config

Fast discovery first, deep reads second:
1. identify stack + workspace shape,
2. identify top-level apps/packages/modules,
3. identify runtime entrypoints,
4. identify test/build/lint commands,
5. identify conventions + sharp edges,
6. decide which subdirs deserve local index.

Deeper reads only to remove ambiguity.

## Writing the root CLAUDE.md

Project-wide index. Adapt structure:

# Project Index

## Purpose
- what repo does
- product/system boundaries

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

## Commands
- key commands for build, test, lint, run, typecheck, repo-wide verification
- real project-specific only

## Architecture Map
- top-level dirs + responsibility each
- one short bullet each

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

## Change Guidance
- repo-wide conventions
- where new code goes
- what not to touch casually
- verification expectations

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

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

Root stays broad. Points Claude to right place, not explain every subsystem.

## Writing nested CLAUDE.md files

Per selected dir, local thin index focused on subtree.

Adapt structure:

# <subtree> Index

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

## Read First
- files/subfolders to inspect first

## Local Structure
- important internal components/modules

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

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

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

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

Keep highly local. No root-level restating unless needed for safe local work.

## Update behavior

If `CLAUDE.md` exists:
- preserve valuable guidance,
- remove duplication,
- tighten vague wording,
- split broad vs local correctly,
- top = most important.

If file too large:
- compress aggressively,
- prose → bullets,
- broad material → root,
- subtree-relevant only locally.

## Quality bar

Good result lets future Claude answer fast:
- What is repo/subtree for?
- Where to start reading?
- Where new code goes?
- What commands verify change?
- What are hidden traps?

Section not answering one of those = cut.

## Final output to the user

After writing, report:
1. files created/updated,
2. why each subdir qualified,
3. dirs intentionally skipped,
4. ambiguous areas lacking signal,
5. top 3 recommendations for future improvement.

Unsure → bias toward fewer, better `CLAUDE.md` files.