Bootstrap Claudemd

Bootstrap CLAUDE.md

Create initial CLAUDE.md files for a repository that has none. Auto-detect the stack, gather ecosystem context, and produce concise files containing only what Claude cannot infer from the code itself.

The user may pass a repo path as an argument, or default to the current working directory.

---

Core Generation Rules

These rules govern every line written. Violating them produces files that are too long, too vague, or duplicate what tooling already enforces.

1. Explore before writing. Read directory structure, manifests, configs, README, and source samples. Never guess or invent details.
2. Don't restate tooling. If a convention is enforced by a linter, formatter, or type checker config in the repo, leave it out.
3. Only verified commands. Copy commands verbatim from package.json scripts, Makefile, justfile, README, or CI config. Mark inferred commands with # inferred.
4. Every constraint needs a reason. "Never do X — because Y." Without a reason, Claude follows the rule in obvious cases and misses edge cases.
5. No secrets. Env var names are fine; values, tokens, and connection strings are not.
6. Be specific or say nothing. Name exact paths, tools, patterns. Vague guidance produces vague results.
7. Keep files concise but complete. Every line must change how Claude behaves. Cut anything inferable from the codebase, anything restating the README, any empty section headers. But do NOT sacrifice coverage for brevity — a thorough 200-line file is better than a thin 50-line file that misses critical patterns.
8. Imperative voice. "Use named exports" not "We tend to prefer named exports."
9. Focus on non-obvious. Surface what Claude cannot infer from code alone: unusual tooling, generated files that must not be edited, non-standard layouts, monorepo conventions, gotchas.
10. Quality test for every line: "If I remove this, will Claude mess up?" No -> delete it. Yes -> keep it.
11. Document data models and their flow. Identify key input/output data shapes (JSON schemas, API types, database structures, dbt models, Terraform state, protobuf, CSV/Parquet schemas). Document: where defined, how they flow through the system, non-obvious shape constraints, what generates or consumes them. Critical when data shapes cross module or repo boundaries.

---

Output Format

Each CLAUDE.md starts with:

Section order (omit any section that doesn't apply — no empty headings):

1. ## Project — 2-4 sentences: what this does, what system it belongs to
2. ## Stack — language, runtime, framework, database, test runner, build tool, with versions where visible
3. ## Commands — build, test, lint, run, and any other commands developers use regularly
4. ## Data Models — key input/output data shapes and how they flow. Where schemas/types are defined, what generates them (codegen, ORM, manual), what consumes them, non-obvious shape constraints (backwards-compatibility rules, required-but-not-validated fields, enum evolution rules), cross-boundary contracts (API shapes shared between repos, database schemas consumed by multiple services). Only what Claude would get wrong without guidance.
5. ## Conventions — non-obvious patterns not enforced by tooling
6. ## Architecture — key module boundaries or data flow, only if non-obvious from directory structure
7. ## Constraints — hard rules Claude must never violate, each with a reason
8. ## Anti-Patterns — Do NOT — things Claude must AVOID doing, each with evidence and a reason. Sourced from: reverted PRs, reviewer pushback, HACK/FIXME comments protecting intentional patterns, production incidents. Format: "Do NOT X — because Y (evidence: PR #N / revert hash / Jira ticket)."
9. ## Testing — only if the approach is non-standard
10. ## Related Systems — sibling repos/services this interacts with, only if the relationship is non-obvious

CLAUDE.md File Types & Locations

| Type | Location | Purpose | |------|----------|---------| | Project root | ./CLAUDE.md | Primary project context (checked into git, shared with team) | | Package-specific | ./packages/*/CLAUDE.md | Module-level context in monorepos | | Subdirectory | Any nested location | Feature/domain-specific context |

Module-Level Files

Same format but scoped to the module. Even shorter — often just Project + Conventions + Constraints.

Every directory is a candidate. The question is not "is this complex enough?" but "does this directory (or its children) have anything non-obvious that Claude needs to know?" Use these rules to decide placement:

• Create a CLAUDE.md in a directory when it has its own conventions, constraints, data flow patterns, or gotchas that differ from or extend the parent CLAUDE.md. Indicators: own build file, specialized tech, distinct coding patterns, high dependency fan-in, high convention density (many behavioral patterns even with few files — e.g., non-obvious return types, reusable utilities, conditional template methods, mock patterns, hack workarounds).
• Roll up into the parent when a subdirectory is simple enough that a brief mention in the parent's CLAUDE.md fully covers it. Indicators for rollup: fewer than 3 source files, no distinct conventions, follows the same patterns as siblings, low convention density (no behavioral surprises found during Step 2b deep-dive).
• Cover children from the parent when multiple subdirectories share the same patterns — document once in the parent rather than repeating in each child. Use a clearly labeled ### Rolled-up subdirectories section in the parent to name each covered child and briefly describe what it contains — so readers know the child was intentionally covered here, not forgotten.

The goal is full coverage: every directory's non-obvious patterns should be documented somewhere — either in its own CLAUDE.md or in an ancestor's. No directory should fall through the cracks.

---

Quality Validation

Before presenting generated content to the user, score each file against this rubric. Include the score in the Step 5 discovery summary.

Scoring Rubric

| Criterion | Max Points | What to check | |-----------|-----------|---------------| | Commands/workflows | 20 | Are build, test, lint, deploy commands present with context? | | Architecture clarity | 20 | Can Claude understand codebase structure, module relationships, entry points? | | Non-obvious patterns | 15 | Are gotchas, quirks, workarounds, and "why we do it this way" captured? | | Conciseness | 15 | No filler, no obvious info, no redundancy with code comments? | | Currency | 15 | Do commands work? Are file references accurate? Tech stack current? | | Actionability | 15 | Are instructions executable and copy-paste ready? Paths real? |

Grades

• A (90-100): Comprehensive, current, actionable
• B (70-89): Good coverage, minor gaps
• C (50-69): Basic info, missing key sections
• D (30-49): Sparse or outdated
• F (0-29): Missing or severely outdated

Target grade A for all generated files. If a file scores below B, revisit the generation rules and fill gaps before presenting.

Red Flags Checklist

Before finalizing any file, verify none of these are present:

• Commands that would fail (wrong paths, missing deps)
• References to files/folders that don't exist
• Outdated tech versions
• Generic advice not specific to the project
• Empty "TODO" items
• Duplicate info across multiple CLAUDE.md files
• Copy-paste from templates without customization

---

Step 1: Identify Target Repo

Default to the current working directory. If the user passed a path argument, use that instead.

1. Verify the directory is a git repo (git rev-parse --git-dir).
2. Extract the GitHub remote URL: git remote get-url origin.
3. Parse the org/repo name for GitHub API calls (e.g., Sage-Bionetworks/Synapse-Repository-Services).
4. If no remote or not a GitHub repo, note the gap and proceed with local-only analysis.

---

Step 2: Explore the Repository (parallel agents)

Launch up to 3 Explore agents in parallel:

Agent 1 — Build system & stack detection

Find and read:

• Manifests: pom.xml, package.json, go.mod, Cargo.toml, requirements.txt, pyproject.toml, build.gradle, Gemfile, *.csproj, Makefile, CMakeLists.txt, *.sln
• Version files: .nvmrc, .java-version, .python-version, .tool-versions, rust-toolchain.toml
• CI configs: .github/workflows/*.yml, Jenkinsfile, .gitlab-ci.yml, buildspec.yml, .circleci/config.yml
• Linter/formatter configs: .eslintrc*, .prettierrc*, tsconfig.json, .flake8, pyproject.toml [tool.*], rustfmt.toml, .editorconfig, checkstyle.xml

Extract:

• Language + version
• Frameworks + versions
• Build/test/lint commands (verbatim from config files)
• List of linter/formatter configs (to know what NOT to put in CLAUDE.md)

Agent 2 — Structure, module candidates & data models

• Map the full directory tree (all levels, not just top-level)
• Include non-code directories. Documentation directories (e.g., docs/) with their own build systems, conventions, or content frameworks are candidates — not just source code directories. Any directory with non-obvious patterns needs coverage.
• Treat every directory as a CLAUDE.md candidate. For each directory, determine:

1. Own file: Does it have conventions, constraints, or patterns that differ from its parent? Indicators: own build file, specialized tech (IaC, codegen, CRDT, DDL, security, custom protocols), distinct coding patterns, high dependency fan-in, history of gotcha patterns, 5+ source files with unique conventions.
2. Roll up to parent: Is it simple enough (few files, no distinct patterns, follows sibling conventions) that a mention in the parent CLAUDE.md suffices?
3. Covered by ancestor: Are its patterns already documented in an ancestor's CLAUDE.md?

• Build a coverage map: for every directory in the repo, note where its patterns will be documented (own file, parent, or ancestor). Present this map in Step 5 so no directory is missed.
• Find generated code directories (flag as "never edit")
• Locate data model definitions: JSON schemas, protobuf files, OpenAPI/Swagger specs, GraphQL schemas, database DDL/migrations, dbt models, TypeScript type definition files, Pydantic models, dataclasses, Terraform resource definitions, Avro/Parquet schemas
• Trace data flow: which modules define schemas, which consume generated types, which share data shapes across boundaries
• Identify codegen pipelines: schema-to-POJO, proto-to-code, OpenAPI-to-client, dbt model compilation

Agent 3 — Conventions & gotchas

• Sample 3-5 source files from different areas of the repo
• Look for non-obvious patterns: unusual import styles, custom error handling, serialization approaches, naming conventions that differ from language defaults
• Read test files for non-standard test patterns (custom runners, unusual directory layouts, integration test infrastructure)
• Check README.md for constraints or setup gotchas
• Look at recent git log (20 commits) for commit message conventions and active areas

---

Step 2b: Deep-Dive Exploration (parallel agents)

This step is critical. Step 2 gives a structural overview. Step 2b reads source files deeply to find behavioral conventions — the non-obvious patterns that cause the most mistakes. Skip this step only for trivially small repos ( PLFM), or search issues mentioning the repo name.

1. mcp__atlassian__searchJiraIssuesUsingJql — active epics: project = AND type = Epic AND status != Done ORDER BY updated DESC (limit 10).
2. Recent completed tickets (last 180 days) for work patterns.

If the project key cannot be determined, ask the user.

Confluence context

Use mcp__atlassian__* tools:

1. mcp__atlassian__searchConfluenceUsingCql — search for text ~ "" AND type = page ORDER BY lastModified DESC (limit 10).
2. Read the top 2-3 results looking for: architecture docs, ADRs, coding standards, design decisions.

Cross-repo detection

• Look for import/dependency references to other repos in build files (e.g., Maven groupId references, npm package names matching other Sage repos)
• Check CI/CD configs for cross-repo triggers or deployments
• If in a workspace with multiple repos, scan sibling directories for related projects

---

Step 4: Filter Through Generation Rules

Before presenting anything to the user, apply the content principles:

1. Remove anything enforced by existing linter/formatter/type checker configs. If .eslintrc enforces semicolons, don't put "Use semicolons" in CLAUDE.md.
2. Remove anything obvious from reading the code. If every file uses the same import style, Claude will pick it up.
3. Remove anything that restates the README.
4. Ensure every remaining item passes the quality test: "If I remove this, will Claude mess up?"
5. Ensure every constraint has a reason.
6. Check data model items: only include shape constraints Claude would get wrong without guidance. Skip shapes that are self-evident from reading schema files.

What NOT to Add — Examples

| Bad (remove) | Why it fails | Good (keep) | |--------------|-------------|-------------| | "The UserService class handles user operations." | Obvious from class name | (omit entirely) | | "Always write tests for new features." | Generic advice, not project-specific | (omit entirely) | | "The authentication system uses JWT tokens. JWT (JSON Web Tokens) are an open standard (RFC 7519)..." | Verbose, encyclopedic | "Auth: JWT with HS256, tokens in Authorization: Bearer header." | | "Use meaningful variable names." | Universal advice | (omit entirely) | | "We fixed a bug in commit abc123 where login broke." | One-off fix, won't recur | (omit entirely) |

Validation Checklist

Before finalizing, verify:

• [ ] Each item is project-specific, not generic advice
• [ ] No obvious info that Claude can infer from code
• [ ] Commands are copy-paste ready and verified against config files
• [ ] All file paths reference real, existing files
• [ ] Every constraint has a "— because Y" reason
• [ ] This is the most concise way to express each item

---

Step 5: Present Discovery Summary

Show the user what was found and what will be generated:

## Repo: 
Examined: 

### Root CLAUDE.md will cover:
- Project: 
- Stack: 
- Commands: 
- Data Models: 
- Conventions: 
- Constraints: 
- [other applicable sections]

### CLAUDE.md placement plan:
#### Own file:
-  — 

#### Rolled up into parent:
-  → covered in /CLAUDE.md — 

#### Covered by ancestor:
-  → already covered by /CLAUDE.md

### From GitHub PRs:
- 

### From Jira:
- 

### From Confluence:
- 

### Estimated total: ~X lines root, ~Y lines per module

Ask the user to confirm, correct, or skip sections before generating.

---

Step 6: Generate Files

See [references/templates.md](references/templates.md) for starter templates by project type.

For each approved CLAUDE.md:

1. Start with `` using the current month.
2. Write each applicable section following the output format.
3. Omit sections that don't apply — no empty headings.
4. Use imperative voice throughout.
5. Keep files concise but complete. Every line must earn its place, but do NOT cut behavioral conventions or reusable utility lists just to hit an arbitrary line count. Thoroughness over brevity.
6. For module-level files, only include what differs from the root CLAUDE.md. Include: reusable utilities that must not be reinvented, non-obvious return types, conditional behavior, mock/test patterns, hack workarounds, naming inconsistencies.

---

Step 7: Review and Write

1. Present each generated file's full content to the user using diff format for easy review:

``` ### File: ./CLAUDE.md Quality Score: XX/100 (Grade: X)

```diff

• ## Project

+

```

> Why this section helps: ```

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Sage-Bionetworks
• Source: Sage-Bionetworks/agent-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.