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/

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

{
  "$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:*)

Bash(pytest:*)

Step 3: Generate CLAUDE.md

Perform deep codebase analysis and generate

.claude/CLAUDE.md

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

• 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/

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:

nextjs-patterns.md

react-components.md

fastapi-patterns.md

nestjs-patterns.md

swiftui-patterns.md

uikit-patterns.md

vapor-patterns.md

compose-patterns.md

android-views-patterns.md

vue-patterns.md

django-patterns.md

rails-patterns.md

spring-patterns.md

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):

paths

typescript.md

["**/*.ts", "**/*.tsx"]

python.md

["**/*.py"]

swift.md

["**/*.swift"]

go.md

["**/*.go"]

rust.md

["**/*.rs"]

Each rule file needs YAML frontmatter with

paths

Step 7: Generate Commands

Write 5 command files to

.claude/commands/

.claude/commands/task.md

---
allowed-tools: ["Read", "Write", "Edit", "Glob"]
description: "Start or switch to a new task"
argument-hint: "<task description>"
---

Instructions to update

.claude/state/task.md

.claude/commands/status.md

---
allowed-tools: ["Read", "Glob", "Bash(git status)"]
description: "Show current task and session state"
---

Instructions to read task.md, show git status, summarize current state.

.claude/commands/done.md

---
allowed-tools: ["Read", "Write", "Edit", "Glob", "Bash(git:*)", "Bash(bun test)"]
description: "Mark current task complete"
---

Instructions to run tests, lint, verify, update task.md status to "Done".

.claude/commands/analyze.md

---
allowed-tools: ["Read", "Glob", "Grep"]
description: "Deep analysis of a specific area"
argument-hint: "<area or file path>"
---

Instructions to perform thorough analysis of specified area.

.claude/commands/code-review.md

---
allowed-tools: ["Read", "Glob", "Grep", "Bash(git diff)"]
description: "Review code changes for quality and security"
---

Instructions to review staged/unstaged changes.

Output Summary

After generating all files, output a brief summary:

• List of files created
• Any gaps found (missing config files, unclear patterns)
• Suggested next steps

Important Guidelines

1. Be specific, not generic. Every file must contain project-specific content.
2. Reference real files. Use

   path/to/file.ts:lineNumber

   format.
3. Use actual commands. Reference the project's real test/lint/build commands.
4. Skip what doesn't apply. Don't generate framework skills for frameworks not in use.
5. Respect existing files. If

   .claude/

   files exist, read and preserve manually-added content.