Bootstrap

/bootstrap — Set Up a Project for Claude Code

First: Read LEARNINGS.md in this skill's directory.

Arguments: $ARGUMENTS

If no project path given, use the current working directory. If --type not specified, infer from context (has src/, package.json, Cargo.toml -> code; otherwise -> knowledge).

Step 1: Reconnaissance

Before creating anything, understand what exists.

1. Read the project's existing README, package.json/Cargo.toml/pyproject.toml, or equivalent
2. ls the top-level directory structure
3. Check if .claude/ already exists — if so, audit what's there and fill gaps instead of overwriting
4. Identify:
   • Tech stack (languages, frameworks, package manager)
   • Build/lint/test commands (from package.json scripts, Makefile, etc.)
   • Major modules (top-level dirs that represent distinct concerns)
   • Project type: code (has source code, build system) or knowledge (notes, docs, automation)

Present findings to the user in a table. Confirm before proceeding.

Step 2: Create Directory Structure

.claude/
  CLAUDE.md              # Behavioral core (always created)
  CODEBASE.md            # Project overview + module index (code projects only)
  docs/                  # Module documentation (code projects only)
    <module>.md          # One per major module
  knowledge/             # On-demand context
    <framework>.md       # Language/framework conventions
  settings.local.json    # Project-scoped settings (if hooks needed)

For knowledge projects, skip CODEBASE.md and docs/. Add instead:

.claude/
  rules/                 # Domain rules (always loaded)
  knowledge/sessions/    # Session logs

Create the directories. Do NOT create empty placeholder files.

Step 3: Write CLAUDE.md

Target: 30-40 lines max. This burns context tokens every session.

Structure — adapt sections to the project:

# <Project Name>

## Commands
- `<build command>` -- build the project
- `<test command>` -- run tests
- `<lint command>` -- lint/typecheck

## Process
- Before starting, read `.claude/CODEBASE.md` and relevant `.claude/docs/` files
- Do NOT use the Explore agent by default -- read documentation first
- After code changes, update documentation if interfaces or behavior changed
- When fetching context, state which documents you loaded

## Available Documentation
- `.claude/CODEBASE.md` -- project overview and module index
- `.claude/docs/<module>.md` -- <one-line description>

## Available Knowledge
- `.claude/knowledge/<topic>.md` -- <one-line description>

What goes in CLAUDE.md: commands, process instructions, file listings. What does NOT go in CLAUDE.md: architecture details (-> CODEBASE.md), code conventions (-> knowledge/), module descriptions (-> docs/).

Step 4: Write CODEBASE.md (Code Projects Only)

The entry point Claude reads first. Include:

1. What the project does (2-3 sentences)
2. Tech stack summary
3. Module index — one line per module linking to its doc file
4. <!-- docs-synced-at: <commit-hash> --> marker on line 1

<!-- docs-synced-at: abc1234 -->
# <Project Name> — Codebase Overview

<What this project does. 2-3 sentences.>

## Tech Stack
<Language, framework, database, key libraries>

## Modules
| Module | Description | Docs |
|--------|-------------|------|
| `src/api/` | REST API routes and handlers | [docs/api.md](docs/api.md) |
| `src/web/` | Frontend application | [docs/web.md](docs/web.md) |

Step 5: Write Module Docs (Code Projects Only)

One file per major module in docs/. Each file:

• What the module does (2-3 sentences)
• Key interfaces and type signatures (actual code, not prose)
• Links to source files
• Important design decisions and why
• Behavioral description (what happens when X is called)

These describe behavior and intent for an agent, not auto-generated API docs.

Use an Agent subagent per module (parallel) to scan source code and produce the doc.

Step 6: Write Knowledge Files

Create knowledge/<topic>.md for each relevant framework/language convention. Only create files for technologies actually used — don't speculate.

For knowledge projects, also create any needed rules/*.md files.

Knowledge file design principles:

• YAML frontmatter on every file (tags, created, last_reviewed, type)
• Imperative phrasing ("Use X for Y" not "X is used for Y")
• Tables over prose for structured data
• 40-80 lines per file, no redundancy — each fact lives in ONE place
• Actionable: "what do I need to know to act", not complete documentation

For knowledge projects, also set up MEMORY.md:

• Under 200 lines always (silently truncated beyond)
• Structure: Active State table, Key Decisions, Next Up, File Map
• Concise index pointing to topic files — not a comprehensive document
• "Next Up" section is mandatory — next session reads this first

Step 7: Configure Hooks (If Needed)

Only add hooks when the project has specific needs:

Write hooks to scripts/ and register in .claude/settings.local.json.

Step 8: Verify

Run through the checklist:

Present the completed checklist to the user.

Step 9: Initial Commit

Stage all .claude/ files. Commit message: feat: bootstrap .claude/ for agentic development

Do NOT push without user approval.

Rules

• Minimal CLAUDE.md is non-negotiable. 30-40 lines. Minimize noise, maximize signal — it gets very bad, very fast if you give information that you might not use.
• Never dump architecture into CLAUDE.md. That's what CODEBASE.md and docs/ are for.
• Docs describe behavior, not API surface. Write for an agent that needs to understand the codebase without reading every file.
• Only create files for things that exist. Don't create knowledge/react.md if the project doesn't use React.
• Third-party projects get isolation. Add to CLAUDE.md: Do NOT update ~/claude-assistant/knowledge/, MEMORY.md, or task backlog for this project.
• Don't over-document. Start lean. Fill gaps over time as you learn what's actually needed.
• Adapt, don't template. Every project is different. The structure above is a guide, not a rigid template. A 3-file Python script doesn't need module docs.