---
name: claude-md-blueprint-generator
description: Technology-agnostic blueprint generator for creating comprehensive CLAUDE.md files that guide Claude Code to produce code consistent with project standards, architecture patterns, and exact technology versions by analyzing existing codebase patterns and avoiding assumptions.
---

# CLAUDE.md Blueprint Generator

## Configuration Variables

- `PROJECT_TYPE` — Auto-detect | .NET | Java | JavaScript | TypeScript | React | Angular | Python | Multiple | Other
- `ARCHITECTURE_STYLE` — Layered | Microservices | Monolithic | Domain-Driven | Event-Driven | Serverless | Mixed
- `CODE_QUALITY_FOCUS` — Maintainability | Performance | Security | Accessibility | Testability | All
- `DOCUMENTATION_LEVEL` — Minimal | Standard | Comprehensive
- `TESTING_REQUIREMENTS` — Unit | Integration | E2E | TDD | BDD | All
- `VERSIONING` — Semantic | CalVer | Custom

Ask the user for any unset variables before generating, or detect sensible defaults from the codebase.

## What this skill does

Generate a comprehensive `CLAUDE.md` file that guides Claude Code to produce code consistent with the project's standards, architecture, and exact technology versions. Instructions must be strictly grounded in the actual code present in the repository — never assume patterns that aren't already there.

Claude Code automatically loads `CLAUDE.md` from:
- The repo root (project-level instructions, committed to git)
- Any parent directory of the working dir (monorepo or workspace roots)
- Subdirectories of the working tree (scoped guidance loaded on-demand)
- `~/.claude/CLAUDE.md` (user-global, not project-specific — do not write here)

Place the generated file at the **repo root** unless the user specifies otherwise. For monorepos, consider one root `CLAUDE.md` plus per-package files.

## Generation procedure

### Step 1 — Analyze the codebase

Before writing anything, scan the repo to ground every claim in real evidence:

1. **Detect exact technology versions**
   - Read manifest files: `package.json`, `pyproject.toml`, `requirements.txt`, `*.csproj`, `pom.xml`, `build.gradle`, `Cargo.toml`, `go.mod`, `Gemfile`, etc.
   - Read language-version indicators: `.nvmrc`, `.python-version`, `tsconfig.json` `target`, `<LangVersion>` in .NET, `rust-toolchain.toml`.
   - Record exact pinned versions, not ranges — Claude must not suggest features beyond what's installed.

2. **Map the architecture**
   - Walk the folder tree; identify layers, modules, bounded contexts.
   - Note entry points, build outputs, and inter-module imports.
   - Identify how components communicate (HTTP, events, direct calls).

3. **Catalog patterns actually in use**
   - Naming conventions for files, types, functions, tests.
   - Error handling style (exceptions vs. result types, where they're caught).
   - Logging library and call style.
   - Test framework, file location, naming, assertion style.
   - Comment/doc style and density.
   - Dependency injection or wiring approach.

4. **Note quality and tooling signals**
   - Lint/format config (`eslint`, `ruff`, `prettier`, `.editorconfig`).
   - CI workflows in `.github/workflows/` or equivalent.
   - Pre-commit hooks, type-check commands, test commands.

Only document patterns you can point to in real files. If something isn't established in the codebase, leave it out — don't import "best practices" from outside.

### Step 2 — Generate the CLAUDE.md

Use the template below. Drop sections that don't apply. Substitute variables and fill in concrete details from Step 1. Reference real files with relative paths so Claude Code can click through.

```markdown
# CLAUDE.md

Project-specific instructions for Claude Code. Read this before generating or modifying code in this repository.

## Priority guidelines

When working in this repo:

1. **Version compatibility** — Respect the exact versions of languages, frameworks, and libraries pinned in this project. Never use features unavailable in the detected versions.
2. **Codebase patterns first** — Mirror the patterns already established in the codebase. Consistency with existing code outweighs external best practices.
3. **Architectural boundaries** — This project follows a ${ARCHITECTURE_STYLE} style. Do not cross established module boundaries without explicit instruction.
4. **Quality focus** — Prioritize ${CODE_QUALITY_FOCUS} (see "Code quality standards" below).
5. **Ground every change in evidence** — Before introducing a pattern, confirm it exists elsewhere in the codebase. If it doesn't, ask before adding it.

## Detected technology stack

<!-- Fill in from Step 1. Use exact versions, not ranges. -->
- Language(s): ...
- Framework(s): ...
- Key libraries: ...
- Test framework: ...
- Lint/format: ...
- Build/run commands: ...

## Project structure

<!-- Describe the actual folder layout and what lives where. Link to real directories. -->
- `path/to/dir/` — purpose
- ...

## Codebase pattern lookup

When you need to write new code, find the closest existing example and match it:

1. Find a similar existing file (same layer, same kind of responsibility).
2. Match its conventions for:
   - Naming (files, types, functions, variables, tests)
   - Imports and module organization
   - Error handling
   - Logging
   - Documentation style
   - Tests (location, naming, structure)
3. When multiple patterns coexist, prefer the one in newer files or files with the most test coverage.
4. Never introduce a pattern not already present.

## Code quality standards

<!-- Include only sections matching ${CODE_QUALITY_FOCUS}. Replace bullets with specifics from this codebase. -->

### Maintainability
- Match naming and organization conventions evident in the codebase.
- Keep functions focused; match length and complexity of existing functions.
- Self-documenting code preferred over comments (but match existing comment density).

### Performance
- Follow existing patterns for async, caching, and resource management.
- Match how the codebase handles expensive operations.

### Security
- Match existing input validation and sanitization patterns.
- Use parameterized queries / prepared statements as the codebase already does.
- Follow established auth and secrets-handling patterns.

### Accessibility
- Match existing ARIA usage, keyboard nav, and contrast patterns in components.

### Testability
- Match the codebase's dependency injection / wiring approach.
- Match mocking and test-double conventions.

## Documentation requirements

<!-- Pick the block matching ${DOCUMENTATION_LEVEL}. -->

**Minimal:** Match the level and style of comments in existing code. Document only non-obvious behavior.

**Standard:** Follow the documentation format used in the codebase. Match JSDoc/XML doc/docstring style and completeness.

**Comprehensive:** Match the most thoroughly documented files. Document parameters, returns, exceptions, and design decisions.

## Testing

<!-- Include subsections matching ${TESTING_REQUIREMENTS}. -->

- Test framework: ...
- Test file location and naming: ...
- Run tests with: `...`

### Unit tests
- Match the structure, naming, and assertion style of existing unit tests.
- Use the same mocking approach already in the codebase.

### Integration tests
- Match existing patterns for setup/teardown, fixtures, and database/state handling.

### End-to-end tests
- Match the existing E2E framework and user-journey patterns.

### TDD / BDD
- If the codebase uses Given-When-Then or red-green-refactor patterns, match them.

## Technology-specific guidelines

<!-- Include only blocks matching ${PROJECT_TYPE}. Replace each bullet with the concrete convention from this codebase. -->

### .NET
- Target framework version: ...
- C# language version: ...
- Match async/await, LINQ, and DI patterns from existing code.

### Java
- JDK version: ...
- Match exception-handling and DI patterns from existing code.

### JavaScript / TypeScript
- TS target / lib: ...
- Module system (ESM/CJS): ...
- Match import order, type definitions, and async patterns from existing files.

### React
- React version: ...
- Function vs. class components: match the established choice.
- State management: ... (Redux / Zustand / context / etc.)
- Match prop typing and hook usage from existing components.

### Angular
- Angular version: ...
- Match decorator, module, and RxJS patterns from existing code.

### Python
- Python version: ...
- Type hints: present / absent — match the codebase.
- Match import order, error handling, and module organization from existing files.

## Versioning

<!-- Pick the block matching ${VERSIONING}. -->

**Semantic:** Follow SemVer. Note breaking changes in commit messages / changelog as the project already does.

**CalVer:** Match the date-based versioning pattern in use.

**Custom:** Match the existing tagging and changelog conventions exactly.

## Commands

<!-- Fill in real commands from package.json scripts / Makefile / CI. -->
- Install: `...`
- Dev / run: `...`
- Build: `...`
- Test: `...`
- Lint / format: `...`
- Type check: `...`

## What not to do

- Do not introduce libraries, patterns, or abstractions that aren't already used here.
- Do not upgrade dependencies as a side effect of unrelated work.
- Do not add comments that restate what the code does — match existing comment density.
- Do not bypass lint/format/type-check failures with `--no-verify` or equivalent.
- Do not generate speculative tests, error handling, or config for cases that don't exist.

## When in doubt

Read a nearby file and match it. If no precedent exists, ask the user before inventing one.
```

### Step 3 — Verify before handing off

- Open the generated `CLAUDE.md` and check every concrete claim against a real file in the repo.
- Remove any section that you couldn't ground in actual code.
- Confirm command-line snippets actually run (`npm test`, `pytest`, etc.).
- Commit the file so it ships with the repo.

## Expected output

A `CLAUDE.md` at the repo root (or appropriate subdirectory) that gives Claude Code the precise context it needs to produce changes consistent with this codebase's real versions, patterns, and architecture — without inventing conventions that don't exist.