Claude Code Starter

You are setting up Claude Code configuration for a project. Follow the flow below to analyze the project and generate all .claude/ configuration files.

Step 1: Detect Project Type

Check if this is a new project (empty or <3 source files) or an existing project.

For new projects, ask the user these questions:

1. What are you building? (project description)
2. Primary language? (TypeScript, JavaScript, Python, Go, Rust, Swift, Kotlin, Java, Ruby, C#, PHP, C++)
3. Framework? (filtered by language — e.g. Next.js/React/Vue for TS/JS, FastAPI/Django/Flask for Python)
4. Package manager? (filtered by language)
5. Testing framework? (filtered by language, or "None")
6. Linter/Formatter? (filtered by language, or "None")
7. Project type? (Web App, API/Backend, CLI Tool, Library/Package, Mobile App, Desktop App, Monorepo, Other)

For existing projects, analyze the codebase:

• Read package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, or equivalent
• Detect languages, frameworks, package manager, testing, linting, formatting, bundler
• Identify architecture patterns, directory structure, code conventions

Step 2: Create .claude/settings.json

Generate settings.json with permissions based on detected stack. Example:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Read(**)", "Edit(**)", "Write(.claude/**)", "Bash(git:*)",
      "Bash(npm:*)", "Bash(node:*)"
    ]
  }
}

Add language/framework-specific permissions (e.g. Bash(cargo:*) for Rust, Bash(pytest:*) for Python).

Step 3: Generate CLAUDE.md

Perform deep codebase analysis and generate .claude/CLAUDE.md following this structure:

Phase 1: Discovery

Read actual project files to discover:

• Project identity (name, version, description, purpose)
• Directory structure map (depth 3)
• Tech stack deep scan (languages, frameworks, database, auth, API layer, styling, build tools, CI/CD)
• Architecture pattern recognition (MVC, Clean, Hexagonal, etc.)
• Entry points and key files
• Code conventions (naming, imports, exports, function style, error handling)
• Development workflow (scripts, env vars, pre-commit hooks, testing setup)
• Domain knowledge (entities, workflows, integrations)

Phase 2: Write CLAUDE.md

Using ONLY discovered information, write .claude/CLAUDE.md with:

• Project name + one-line description
• Overview (purpose, audience, value proposition)
• Architecture (pattern, directory structure, data flow, key files)
• Tech stack table
• Development setup (prerequisites, getting started, env variables)
• Common commands
• Code conventions (naming patterns, patterns to follow, anti-patterns)
• Testing (commands, writing patterns)
• Domain knowledge (entities, workflows)
• Gotchas & important notes
• Rules

Phase 3: Quality Check

Verify every section contains project-specific content, not generic boilerplate. Skip sections without real content.

Step 4: Generate Skills

Write each skill file to .claude/skills/ with YAML frontmatter (name, description, globs).

Core Skills (ALWAYS generate all 8):

1. .claude/skills/pattern-discovery.md — Analyze codebase to discover and document patterns. Include project-specific search strategies based on the actual directory structure and file patterns found.

2. .claude/skills/systematic-debugging.md — 4-phase methodology: Reproduce, Locate, Diagnose, Fix. Tailor reproduction steps to the project's actual test runner and dev server commands.

3. .claude/skills/testing-methodology.md — AAA pattern (Arrange, Act, Assert). Use the project's actual testing framework syntax (e.g., describe/it for Jest/Vitest, def test_ for pytest). Include mocking patterns specific to the stack.

4. .claude/skills/iterative-development.md — TDD workflow loop: write failing test → implement → verify → refactor. Use the project's actual test command and lint command.

5. .claude/skills/commit-hygiene.md — Atomic commits, conventional commit format, size thresholds (±300 lines), when-to-commit triggers.

6. .claude/skills/code-deduplication.md — Check-before-write principle. Search existing code before writing new code. Include project-specific glob patterns for common file types.

7. .claude/skills/simplicity-rules.md — Function length limits (≤40 lines), file limits (≤300 lines), cyclomatic complexity constraints. Decomposition patterns.

8. .claude/skills/security.md — .gitignore entries for the stack, environment variable handling patterns, OWASP checklist items relevant to the detected framework.

Framework-Specific Skills (ONLY if detected):

Generate the appropriate skill based on detected frameworks:

Tailor ALL skill content to the specific project's patterns, file structure, and conventions discovered during analysis.

Step 5: Generate Agents

Write 2 agent files to .claude/agents/:

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code for quality, security issues, and best practices
tools:
  - Read
  - Grep
  - Glob
  - "Bash(biome check .)"  # Use actual lint command
disallowed_tools:
  - Write
  - Edit
model: sonnet
---

Body: Instructions for reviewing code quality, security, naming conventions, test coverage, and adherence to project patterns.

.claude/agents/test-writer.md

---
name: test-writer
description: Generates comprehensive tests for code
tools:
  - Read
  - Grep
  - Glob
  - Write
  - Edit
  - "Bash(bun test)"  # Use actual test command
model: sonnet
---

Body: Instructions for writing tests using the project's actual testing framework, following existing test patterns.

Step 6: Generate Rules

Write rule files to .claude/rules/:

Always Generate:

• .claude/rules/code-style.md — Formatting tool, comment style, error handling, git commit conventions.

Conditional (by language):

Each rule file needs YAML frontmatter with paths for file matching.

Step 7: Generate Commands

Write 5 command files to .claude/commands/:

.claude/commands/task.md

---
allowed-tools: ["Read", "Write",