Project CLAUDE.md Generator

Overview

Generate and maintain standardized CLAUDE.md files that serve as AI configuration + routing index for Claude Code. NOT a project documentation template — a concise, AI-optimized config file.

Core principle: CLAUDE.md is the only file auto-injected into every CC conversation. Every line must earn its place. If it's derivable from code, don't write it. If it's longer than 150 lines, refactor to routing.

When to Use

• User says "init project", "新项目", "创建 CLAUDE.md", "project init"
• Entering a project directory without CLAUDE.md
• User asks to review/improve their CLAUDE.md

When NOT to use:

• Project already has a well-structured CLAUDE.md and user isn't asking about it
• Non-project directories (home dir, tmp, etc.)

Design Principles

These principles emerged from multi-model debate (7 frontier models):

1. AI Config, Not Documentation — CLAUDE.md tells AI "how to operate here", not "what this project is about". README is for humans, CLAUDE.md is for AI.
2. Token Economy — Every line auto-injected = permanent context cost. Keep ≤150 lines.
3. Route, Don't Duplicate — Point to existing docs (README, ADRs, architecture.md) instead of duplicating content.
4. Flexible, Not Rigid — Core sections are required; optional sections adapt to project maturity.
5. Code as Truth — Architecture, dependencies, data flow should be read from code, not manually documented in CLAUDE.md.
6. Scan First, Ask Second — Auto-detect what you can from project files, only ask about things that can't be inferred.

The Protocol

Section Structure

CORE (required):
  # Project + one-liner
  ## Why
  ## Codebase Navigation
  ## Constraints & Gotchas

OPTIONAL (recommended):
  ## Commands
  ## Current Focus
  ## Context Links

Template

# Project: <name>
> 一句话定义这个项目做什么

## Why
- 解决什么问题，为谁解决
- 目标（1-2 个，可量化）
- Non-goals: <明确不做什么>（可选）

## Codebase Navigation
入口: <path>
核心逻辑: <path>
配置: <path>
测试: <path>

## Constraints & Gotchas
- <编码约束：如"不要用 any 类型">
- <框架约束：如"测试用 vitest 不是 jest">
- <目录约束：如"不要修改 legacy/ 目录">
- <风格约束：如"偏好函数式风格">

## Commands
- Build: <command>
- Test: <command>
- Lint: <command>
- Dev: <command>

## Current Focus
- 阶段: [Concept | MVP | Alpha | Beta | Production]
- 当前: <正在做的事>
- Last updated: <date>

## Context Links
- Architecture: <path or "N/A">
- Decisions (ADR): <path or "N/A">
- API Spec: <path or "N/A">
- Contributing: <path or "N/A">

Section Details

# Project + one-liner (CORE)

• Project name from package.json / Cargo.toml / go.mod / directory name
• One-liner: what it does in ≤15 words
• Auto-detectable: YES (from README first line, package description)

## Why (CORE)

• NOT a full problem statement or vision document
• 3-5 lines max. Problem + goals + non-goals
• Auto-detectable: PARTIAL (can extract from README, but user confirmation needed)

## Codebase Navigation (CORE)

• Tell AI where the important code lives
• Key-value format: role: path
• Auto-detectable: YES (scan directory structure)
• This is the highest-value section for AI — reduces exploration time dramatically

## Constraints & Gotchas (CORE)

• What NOT to do. What's non-obvious.
• This is the "negative constraints" section — prevents AI from making common mistakes
• Examples: "Don't use dayjs, use date-fns", "All API routes need auth middleware", "DB migrations are manual, never auto-generate"
• Auto-detectable: NO (must ask user)

## Commands (OPTIONAL)

• Build, test, lint, dev server commands
• Auto-detectable: YES (from package.json scripts, Makefile, Cargo.toml)

## Current Focus (OPTIONAL)

• Project stage + what's being worked on now
• Include Last updated timestamp so CC can gauge freshness
• Auto-detectable: PARTIAL (stage from git activity, focus from recent commits)

## Context Links (OPTIONAL)

• Pointers to detailed docs that CC should read on-demand
• Replaces the need for Architecture / Key Decisions / Dependencies sections in CLAUDE.md
• CC reads these lazily — only when the current task needs that context

Skill Behavior

Mode 1: New CLAUDE.md (no file exists)

Step 1: DEEP SCAN — Build independent understanding of the project
  Sources (read ALL available):
  - package.json / Cargo.toml / go.mod / pyproject.toml → name, tech stack, deps
  - Directory structure (full tree, depth 3) → codebase navigation, project type
  - README.md / docs/ → stated purpose, existing documentation
  - Makefile / scripts/ / CI configs → commands, workflows
  - git log --oneline -30 → activity patterns, contributors, current momentum
  - git log --since="2 weeks ago" --stat → recent focus areas
  - Key source files (entry points, main modules) → actual architecture
  - Test files → testing approach, coverage areas
  - .env.example / config files → environment dependencies

Step 2: ANALYZE — Form hypotheses about the project
  Based on the scan, form your own understanding of:
  - What this project ACTUALLY does (not just what README says)
  - What stage it's in (code maturity vs claimed stage)
  - Where the complexity lives (which modules are largest/most active)
  - What's missing or inconsistent (tests? docs? error handling?)
  - What the implicit constraints are (tech debt, patterns, conventions)

Step 3: PRESENT FINDINGS — Share your analysis with the user
  Before asking questions, SHOW what you found:
  "Based on my analysis of the codebase:
   - 这个项目看起来是 [你的理解]
   - 核心复杂度集中在 [模块]
   - 我注意到 [有意思的发现/矛盾/gap]
   - 当前活跃开发集中在 [区域]"

Step 4: SOCRATIC CLARIFICATION — Ask probing questions
  Don't just ask "这个项目做什么". Ask questions that:
  - Challenge unclear assumptions: "README 说这是一个 X，但代码结构更像 Y，实际定位是？"
  - Surface hidden constraints: "我看到 [模块] 没有测试，是刻意的还是技术债？"
  - Clarify scope: "git log 显示最近密集修改 [区域]，这是重构还是新功能？"
  - Probe non-goals: "你选了 [技术A] 而不是 [技术B]，背后的 trade-off 是什么？"
  - Find the real problem: "如果一个新的 CC session 进来改这个项目，最容易犯的错误是什么？"

  Question design principles:
  - 每个问题都基于你的扫描发现，不是泛泛而问
  - 提供你的假设，让用户确认/纠正，而不是开放式提问
  - 问"为什么不"比问"为什么"更能挖出约束
  - 一轮 3-5 个问题，如果回答触发新疑问，可以追问 1-2 轮

Step 5: DRAFT — Generate CLAUDE.md incorporating clarification results
  - Merge auto-detected facts + user clarifications
  - Mark low-confidence content with [待确认]
  - Apply 150-line limit check

Step 6: REVIEW — Present draft, invite final edits
  - Highlight which parts came from代码分析 vs 用户输入
  - Flag any remaining ambiguities

Mode 2: Existing CLAUDE.md — Deep Review (user asks to review/improve)

Step 1: READ — Parse existing CLAUDE.md sections

Step 2: DEEP SCAN — Same thorough scan as Mode 1
  Read code, git history, tests, configs — form independent understanding

Step 3: CROSS-VALIDATE — Compare CLAUDE.md claims against code reality
  Look for:
  - STALE INFO: CLAUDE.md says "阶段: MVP" but git shows 200+ commits and CI/CD
  - MISSING CONTEXT: Complex module with no mention in Constraints/Gotchas
  - OVER-DOCUMENTATION: Sections that repeat what package.json already says
  - UNDER-DOCUMENTATION: Non-obvious patterns that would trip up a new CC session
  - WRONG NAVIGATION: Codebase Navigation paths that don't match current structure
  - IMPLICIT CONSTRAINTS: Code patterns (e.g., always uses X pattern) not documented
  - DRIFT: Architecture description doesn't match actual code structure

Step 4: PRESENT GAPS — Show the divergence, don't just list missing sections
  Instead of "你缺少 Commands section", say:
  "你的 CLAUDE.md 说核心逻辑在 src/core/，但 git log 显示最近 80% 的改动在 src/adapters/，
   而且 adapters/ 里有些非显而易见的约定（所有 adapter 都必须实现 cleanup() 方法），
   这些应该加到 Constraints 里。"

Step 5: PROBE DEEPER — Ask about what the code can't tell you
  - "CLAUDE.md 没提到 [模块]，但它有 2000 行代码和 0 个测试，是什么情况？"
  - "你列了 5 个约束，但我在代码里发现还有 [隐式约束]，要不要加上？"
  - "Current Focus 上次更新是 3 个月前，现在实际在做什么？"
  - "有没有最近踩过的坑，应该记录下来防止 CC 再犯？"

Step 6: PROPOSE EDITS — Specific, targeted improvements
  - Show exact edit suggestions (old → new)
  - Explain WHY each change matters for CC effectiveness
  - Never overwrite — all changes need user approval

Mode 3: Existing Project, No CLAUDE.md — Proactive Init

When CC enters a project directory without CLAUDE.md and the user triggers init:

Step 1-3: Same as Mode 1 (Deep Scan → Analyze → Present Findings)

Step 4: DEEPER PROBING for established projects
  Established projects have MORE implicit knowledge to surface:
  - "这个项目已经有 [N] 个 commit 了，最核心的设计决策是什么？"
  - "我看到 [pattern] 在多个文件中重复出现，这是有意的架构选择吗？"
  - "有没有新人加入时最容易搞错的事情？"
  - "哪些目录/文件是绝对不能随便改的？"

  For mature projects, expect 2-3 rounds of clarification.
  Each round should build on the previous answers.

Step 5-6: Same as Mode 1 (Draft → Review)

Mode 4: Quick Template (user says "just give me the template")

- Output the template directly
- No scanning, no questions
- Let user fill it manually

Clarification Philosophy

The goal of clarification is NOT to fill template fields. It's to surface tacit knowledge that:

• Lives in the team's heads but not in code or docs
• Would cause a new CC session to make mistakes
• Represents non-obvious constraints or trade-offs

Good vs Bad Questions

BAD (form-filling):
  "项目的 Vision 是什么？"
  "请描述你的架构。"
  "你有什么依赖？"

GOOD (insight-probing):
  "README 说目标是 'fast and reliable'，但我看到 src/cache.ts 有大量
   复杂的 retry 逻辑。是不是 reliability 的优先级其实远高于 speed？"
  "你选了 SQLite 但数据模型有 5 张关联表，是单机场景还是后面可能迁移？"
  "tests/ 下只有 unit test，没有 integration test，是刻意的还是待补的？"

When to Stop Asking

• User gives clear, decisive answers → move to draft
• User says "差不多了" / "先这样" → respect it, generate with what you have
• Already asked 2 full rounds (6-10 questions) → draft with [待确认] markers
• User provides very detailed initial description → reduce questions, confirm key points

Anti-patterns

Do NOT:

• Turn CLAUDE.md into a README clone
• Add Problem Statement as a multi-paragraph essay
• Include dependency lists (package.json already has this)
• Add architecture diagrams or detailed data flow (use Context Links)
• Force users to fill optional sections
• Auto-commit the generated file
• Add Key Decisions table directly in CLAUDE.md (use ADR files + Context Link)
• Ask generic form-filling questions ("你的 vision 是什么？") — always base questions on scan findings
• Accept surface-level answers without probing — if user says "就是一个 API 服务", follow up with what makes THIS API service different
• Skip the scan and go straight to questions — your analysis provides the context for meaningful questions
• Ask more than 5 questions in a single round — batch them, wait for answers, then follow up
• Keep asking when the user signals "够了" — respect their pace, generate with what you have

Line Budget Guide

Section	Target Lines	Hard Max
Project + one-liner	2	3
Why	3-5	8
Codebase Navigation	4-6	10
Constraints & Gotchas	3-8	15
Commands	3-5	8
Current Focus	2-3	5
Context Links	3-5	8
Total	~30-40	≤150

Examples

Minimal (small script/tool)

# Project: img-resize
> CLI tool for batch image resizing with quality presets

## Why
- 解决批量图片压缩的重复劳动
- 目标: 一行命令处理整个目录

## Codebase Navigation
入口: src/cli.ts
核心逻辑: src/resize.ts
配置: src/presets.ts

## Constraints & Gotchas
- 使用 sharp 不是 jimp（性能原因）
- 输出目录必须预先存在，不自动创建

Standard (web service)

# Project: api-gateway
> Internal API gateway for microservices routing and auth

## Why
- 统一内部服务的认证和路由
- 目标: 替换 nginx 配置地狱，支持动态路由
- Non-goals: 不做流量管理/rate limiting（用 Istio）

## Codebase Navigation
入口: src/server.ts
路由: src/routes/
中间件: src/middleware/
配置: config/
数据库: src/db/ (Prisma)
测试: tests/

## Constraints & Gotchas
- 所有路由必须经过 auth middleware，无例外
- 不要直接操作 SQL，统一用 Prisma client
- 环境变量通过 config/env.ts 加载，不要用 process.env
- JWT secret 在 vault 里，不在 .env

## Commands
- Dev: pnpm dev
- Test: pnpm test
- Build: pnpm build
- DB migrate: pnpm prisma migrate dev

## Current Focus
- 阶段: Beta
- 当前: 迁移 user-service 路由到新 gateway
- Last updated: 2026-03-30

## Context Links
- Architecture: docs/architecture.md
- Decisions: docs/adr/
- API Spec: openapi/gateway.yaml

Mature (large project)

# Project: data-pipeline
> Real-time data ingestion and transformation platform (Kafka → Flink → ClickHouse)

## Why
- 替换离线 T+1 报表为实时数据分析
- 目标: 端到端延迟 <5s, 日处理量 10B+ events
- Non-goals: 不做 ML feature store（独立项目）

## Codebase Navigation
入口: src/main/java/com/corp/pipeline/Application.java
数据源连接器: src/main/java/.../connectors/
转换逻辑: src/main/java/.../transforms/
输出 sink: src/main/java/.../sinks/
配置: src/main/resources/
Flink jobs: src/main/java/.../jobs/
测试: src/test/

## Constraints & Gotchas
- Flink job 修改后必须做 savepoint 兼容性测试
- ClickHouse 表结构变更需要走 DBA 审批流程
- Kafka topic 命名: {team}.{domain}.{event}.{version}
- 不要在 transform 里做网络调用（Flink 反模式）
- 所有时间戳统一 UTC，不要用本地时区

## Commands
- Build: mvn clean package -DskipTests
- Test: mvn test
- Run local: docker-compose up -d && mvn exec:java
- Deploy: scripts/deploy.sh [env]

## Current Focus
- 阶段: Production
- 当前: 优化 ClickHouse 写入性能（批量合并）
- Last updated: 2026-03-28

## Context Links
- Architecture: docs/architecture.md
- Decisions: docs/adr/
- Runbook: docs/runbook.md
- Monitoring: grafana.internal/d/pipeline-health
- Kafka topics: docs/kafka-topics.md