Back to Details

generate-claudemd

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Generate CLAUDE.md Skill

生成CLAUDE.md Skill

Operator Context

操作场景

This skill operates as an operator for CLAUDE.md generation, configuring Claude's behavior for systematic repository analysis and project-specific documentation creation. It implements a 4-phase pipeline -- SCAN repo facts, DETECT domain enrichment, GENERATE from template, VALIDATE output -- producing a CLAUDE.md that makes new Claude sessions immediately productive.
本Skill作为CLAUDE.md生成的操作工具，配置Claude的行为以进行系统化的仓库分析和项目专属文档创建。它实现了一个四阶段流水线——SCAN（扫描仓库事实）、DETECT（检测领域增强项）、GENERATE（基于模板生成）、VALIDATE（验证输出）——生成的CLAUDE.md可让新的Claude会话立即高效工作。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

  • Analyze Before Writing: Every section MUST be derived from actual repo analysis (reading files, parsing configs, checking paths). Why: guessed content wastes the context window and teaches Claude wrong patterns for the project. Never fill a section from assumptions.
  • Template Conformance: Output follows 
    ${CLAUDE_SKILL_DIR}/references/CLAUDEMD_TEMPLATE.md
    structure. Why: consistent structure means Claude sessions can parse CLAUDE.md predictably across projects.
  • Path Verification: Every path mentioned in the output MUST exist. Every command MUST be runnable. Why: a CLAUDE.md with broken paths is worse than no CLAUDE.md -- it teaches Claude to trust wrong information.
  • No Generic Advice: Phrases like "use meaningful variable names", "write clean code", or "follow best practices" are banned. Why: generic advice wastes tokens and provides zero signal. Only project-specific facts belong in CLAUDE.md.
  • No Overwrite Without Confirmation: If CLAUDE.md already exists, write to 
    CLAUDE.md.generated
    and show a diff. Why: overwriting an existing, potentially hand-tuned CLAUDE.md destroys work.
  • 先分析再编写：每个部分必须源自对仓库的实际分析（读取文件、解析配置、检查路径）。原因：猜测的内容会浪费上下文窗口，还会让Claude学习到项目的错误模式。绝不能凭假设填充任何部分。
  • 遵循模板规范：输出需遵循
    ${CLAUDE_SKILL_DIR}/references/CLAUDEMD_TEMPLATE.md
    的结构。原因：一致的结构能让Claude会话在不同项目中都能可靠解析CLAUDE.md。
  • 路径验证：输出中提到的每个路径必须真实存在，每个命令必须可运行。原因：包含无效路径的CLAUDE.md还不如没有——它会让Claude信任错误信息。
  • 禁止通用建议：禁止出现「使用有意义的变量名」「编写清晰代码」「遵循最佳实践」这类表述。原因：通用建议会浪费token，且没有任何实际价值。只有项目专属的事实才应出现在CLAUDE.md中。
  • 无确认不覆盖：若CLAUDE.md已存在，则写入
    CLAUDE.md.generated
    并展示差异。原因：覆盖已有的、可能经过人工调优的CLAUDE.md会破坏已有工作。

Default Behaviors (ON unless disabled)

默认行为（除非禁用否则生效）

  • Domain Enrichment: Auto-detect repo domain in Phase 2 and load domain-specific patterns (sapcc Go conventions, OpenStack patterns, etc.)
  • Makefile Analysis: Parse Makefile targets for build commands rather than guessing. Why: the Makefile IS the source of truth for build commands in most repos.
  • License Header Detection: Note SPDX conventions if present in source files
  • 领域增强：在第二阶段自动检测仓库领域，并加载领域特定模式（sapcc Go规范、OpenStack模式等）
  • Makefile分析：解析Makefile中的目标以获取构建命令，而非猜测。原因：在大多数仓库中，Makefile是构建命令的权威来源。
  • 许可证头检测：若源代码中存在SPDX规范，则记录相关信息

Why No 
context: fork

为何不使用
context: fork

This skill requires interactive user gates (confirmation when CLAUDE.md already exists, review of generated output). Running in a forked context would bypass these safety checks.
本Skill需要交互式的用户确认环节（CLAUDE.md已存在时的确认、生成输出的审核）。在forked上下文运行会绕过这些安全检查。

Optional Behaviors (OFF unless enabled)

可选行为（除非启用否则关闭）

  • Subdirectory CLAUDE.md: Generate per-package CLAUDE.md files for monorepos (on explicit request)
  • Minimal Mode: Only 3 sections -- Overview, Commands, Architecture (on explicit request: "minimal claude.md")
  • 子目录CLAUDE.md：为单体仓库生成每个包专属的CLAUDE.md文件（需明确请求）
  • 极简模式：仅包含3个部分——概述、命令、架构（需明确请求：「minimal claude.md」）

What This Skill CAN Do

本Skill能做什么

  • Analyze a repository and produce a complete, project-specific CLAUDE.md
  • Detect language, framework, build system, and test infrastructure from config files
  • Load domain-specific enrichment (sapcc Go conventions, OpenStack patterns, etc.)
  • Verify every path and command in the generated output
  • Safely handle repos that already have a CLAUDE.md
  • 分析仓库并生成完整的、项目专属的CLAUDE.md
  • 从配置文件中检测语言、框架、构建系统和测试基础设施
  • 加载领域特定增强内容（sapcc Go规范、OpenStack模式等）
  • 验证生成输出中的所有路径和命令
  • 安全处理已存在CLAUDE.md的仓库

What This Skill CANNOT Do

本Skill不能做什么

  • Improve an existing CLAUDE.md (use 
    claude-md-improver
    for that)
  • Generate documentation for code it cannot read (private dependencies, encrypted configs)
  • Understand runtime behavior (it reads static files, does not execute the project)
  • Replace domain expertise (enrichment patterns are templates, not deep knowledge)
  • 改进已有的CLAUDE.md（请使用
    claude-md-improver
    ）
  • 为无法读取的代码生成文档（私有依赖、加密配置）
  • 理解运行时行为（仅读取静态文件，不执行项目代码）
  • 替代领域专业知识（增强模式是模板，而非深度知识）

Instructions

操作步骤

Execute all phases sequentially. Verify each gate before advancing. Load the template from 
${CLAUDE_SKILL_DIR}/references/CLAUDEMD_TEMPLATE.md
before Phase 3.
按顺序执行所有阶段，推进前需验证每个检查点。在第三阶段前，先从
${CLAUDE_SKILL_DIR}/references/CLAUDEMD_TEMPLATE.md
加载模板。

Phase 1: SCAN

阶段1：SCAN（扫描）

Goal: Gather facts about the repository -- language, build system, directory structure, test patterns, config approach.
Step 1: Check for existing CLAUDE.md
bash
ls -la CLAUDE.md .claude/CLAUDE.md 2>/dev/null
If a CLAUDE.md already exists:
  • Inform the user: "CLAUDE.md already exists. Output will be written to CLAUDE.md.generated so you can compare."
  • Set output path to 
    CLAUDE.md.generated
  • Continue with all phases (the generated file is still useful for comparison)
If no CLAUDE.md exists:
  • Set output path to 
    CLAUDE.md
Step 2: Detect language and framework
Check root directory for language indicators:
FileLanguage/Framework
go.mod
Go
package.json
Node.js / TypeScript
pyproject.toml
, 
setup.py
, 
requirements.txt
Python
Cargo.toml
Rust
pom.xml
, 
build.gradle
Java
Gemfile
Ruby
mix.exs
Elixir
Read the detected config file to extract: project name, dependencies, language version.
For Go projects, also check:
bash
undefined
目标：收集仓库的事实信息——语言、构建系统、目录结构、测试模式、配置方式。
步骤1：检查是否存在CLAUDE.md
bash
ls -la CLAUDE.md .claude/CLAUDE.md 2>/dev/null
若CLAUDE.md已存在：
  • 告知用户：「CLAUDE.md已存在。输出将写入CLAUDE.md.generated以便您对比。」
  • 设置输出路径为
    CLAUDE.md.generated
  • 继续执行所有阶段（生成的文件仍可用于对比）
若CLAUDE.md不存在：
  • 设置输出路径为
    CLAUDE.md
步骤2：检测语言和框架
检查根目录中的语言标识文件：
文件语言/框架
go.mod
Go
package.json
Node.js / TypeScript
pyproject.toml
, 
setup.py
, 
requirements.txt
Python
Cargo.toml
Rust
pom.xml
, 
build.gradle
Java
Gemfile
Ruby
mix.exs
Elixir
读取检测到的配置文件，提取：项目名称、依赖、语言版本。
对于Go项目，还需检查：
bash
undefined

Read go.mod for module path and Go version

读取go.mod获取模块路径和Go版本

head -5 go.mod

For Node.js projects:
```bash
head -5 go.mod

对于Node.js项目：
```bash

Read package.json for name, scripts, and key dependencies

读取package.json获取名称、脚本和核心依赖

cat package.json | head -30

**Step 3: Parse build system**

Check for build tools and extract commands:

```bash
cat package.json | head -30

**步骤3：解析构建系统**

检查构建工具并提取命令：

```bash

Check for Makefile

检查是否存在Makefile

ls Makefile makefile GNUmakefile 2>/dev/null
ls Makefile makefile GNUmakefile 2>/dev/null

If Makefile exists, extract targets

若存在Makefile，提取目标

grep -E '^[a-zA-Z_-]+:' Makefile 2>/dev/null | head -20

Also check for:
- `package.json` scripts section
- `Taskfile.yml`
- `justfile`
- CI config (`.github/workflows/`, `.gitlab-ci.yml`)

Record: build command, test command, lint command, "check everything" command.

**Step 4: Map directory structure**

```bash
grep -E '^[a-zA-Z_-]+:' Makefile 2>/dev/null | head -20

同时检查：
- `package.json`的scripts部分
- `Taskfile.yml`
- `justfile`
- CI配置（`.github/workflows/`, `.gitlab-ci.yml`）

记录：构建命令、测试命令、lint命令、「全量检查」命令。

**步骤4：梳理目录结构**

```bash

Top-level directories with purpose indicators

带有用途标识的顶层目录

ls -d */ 2>/dev/null

For Go projects, also examine:
```bash
ls -d */ 2>/dev/null

对于Go项目，还需检查：
```bash

Internal packages

内部包

ls internal/ 2>/dev/null ls cmd/ 2>/dev/null ls pkg/ 2>/dev/null

Categorize directories by role (source, test, config, docs, build, vendor).

**Step 5: Find test patterns**

```bash
ls internal/ 2>/dev/null ls cmd/ 2>/dev/null ls pkg/ 2>/dev/null

按角色对目录分类（源码、测试、配置、文档、构建、依赖）。

**步骤5：查找测试模式**

```bash

Detect test framework and patterns

检测测试框架和模式

Go

Go

ls *_test.go 2>/dev/null | head -5
ls *_test.go 2>/dev/null | head -5

Node.js

Node.js

ls *.test.ts *.test.js *.spec.ts *.spec.js 2>/dev/null | head -5
ls *.test.ts *.test.js *.spec.ts *.spec.js 2>/dev/null | head -5

Python

Python

ls test_*.py *_test.py 2>/dev/null | head -5

Read 1-2 representative test files to identify: test framework, assertion library, mocking approach, naming conventions.

**Step 6: Detect configuration approach**

```bash
ls test_*.py *_test.py 2>/dev/null | head -5

读取1-2个代表性测试文件，识别：测试框架、断言库、Mock方式、命名规范。

**步骤6：检测配置方式**

```bash

Environment-based config

基于环境变量的配置

ls .env.example .env.sample 2>/dev/null
ls .env.example .env.sample 2>/dev/null

File-based config

基于文件的配置

ls config.yaml config.json *.toml *.ini 2>/dev/null
ls config.yaml config.json *.toml *.ini 2>/dev/null

Go flag-based or env-based

Go基于flag或环境变量的配置

grep -r 'os.Getenv|flag.|viper.|envconfig' --include='*.go' -l 2>/dev/null | head -5

**Step 7: Detect code style tooling**

```bash
grep -r 'os.Getenv\|flag\.\|viper\.\|envconfig' --include='*.go' -l 2>/dev/null | head -5

**步骤7：检测代码风格工具**

```bash

Linters and formatters

代码检查器和格式化工具

ls .golangci.yml .eslintrc* .prettierrc* .flake8 pyproject.toml .editorconfig 2>/dev/null

If a linter config exists, read it to extract key rules.

**Step 8: Check for license headers**

```bash
ls .golangci.yml .eslintrc* .prettierrc* .flake8 pyproject.toml .editorconfig 2>/dev/null

若存在代码检查器配置文件，读取并提取关键规则。

**步骤8：检查许可证头**

```bash

Look for SPDX headers in source files

在源码文件中查找SPDX头

grep -r 'SPDX-License-Identifier' --include='.go' --include='.py' --include='*.ts' -l 2>/dev/null | head -3

If found, note the license type and header convention.

**GATE**: Language detected. Build targets identified. Directory structure mapped. Test patterns found (or noted as absent). Config approach documented. Proceed ONLY when gate passes.

---
grep -r 'SPDX-License-Identifier' --include='.go' --include='.py' --include='*.ts' -l 2>/dev/null | head -3

若找到，记录许可证类型和头规范。

**检查点**：已检测到语言。已识别构建目标。已梳理目录结构。已找到测试模式（或记录为不存在）。已记录配置方式。仅当检查点通过后，方可继续。

---

Phase 2: DETECT

阶段2：DETECT（检测）

Goal: Identify domain-specific enrichment sources based on repo characteristics.
Step 1: Check for sapcc domain (Go repos)
If Go project detected:
bash
undefined
目标：基于仓库特征识别领域特定增强源。
步骤1：检查是否为sapcc领域（Go仓库）
若检测到Go项目：
bash
undefined

Check go.mod for sapcc imports

检查go.mod中是否有sapcc导入

grep -i 'sapcc|sap-' go.mod 2>/dev/null
grep -i 'sapcc\|sap-' go.mod 2>/dev/null

Check for sapcc-specific packages

检查是否有sapcc专属包

grep -r 'github.com/sapcc' --include='*.go' -l 2>/dev/null | head -5

If sapcc imports found, load enrichment from `go-sapcc-conventions` skill patterns:
- Anti-over-engineering principles
- Error wrapping conventions (`fmt.Errorf("...: %w", err)`)
- `must.Return` scope rules
- Testing patterns (table-driven tests, assertion libraries)
- Makefile management via `go-makefile-maker`

**Step 2: Check for OpenStack/Gophercloud**

```bash
grep -i 'gophercloud\|openstack' go.mod 2>/dev/null
grep -r 'gophercloud' --include='*.go' -l 2>/dev/null | head -5
If found, note OpenStack API patterns, Keystone auth, and endpoint catalog usage.
Step 3: Detect database drivers
bash
undefined
grep -r 'github.com/sapcc' --include='*.go' -l 2>/dev/null | head -5

若找到sapcc导入，从`go-sapcc-conventions` Skill模式中加载增强内容：
- 反过度设计原则
- 错误包装规范（`fmt.Errorf("...: %w", err)`）
- `must.Return`作用域规则
- 测试模式（表驱动测试、断言库）
- 通过`go-makefile-maker`管理Makefile

**步骤2：检查是否为OpenStack/Gophercloud**

```bash
grep -i 'gophercloud\\|openstack' go.mod 2>/dev/null
grep -r 'gophercloud' --include='*.go' -l 2>/dev/null | head -5
若找到，记录OpenStack API模式、Keystone认证和端点目录用法。
步骤3：检测数据库驱动
bash
undefined

Go

Go

grep -E 'database/sql|pgx|gorm|sqlx|ent' go.mod 2>/dev/null
grep -E 'database/sql|pgx|gorm|sqlx|ent' go.mod 2>/dev/null

Node.js

Node.js

grep -E '"pg"|"mysql"|"prisma"|"typeorm"|"knex"|"drizzle"' package.json 2>/dev/null
grep -E '"pg"|"mysql"|"prisma"|"typeorm"|"knex"|"drizzle"' package.json 2>/dev/null

Python

Python

grep -E 'sqlalchemy|django|psycopg|asyncpg' pyproject.toml requirements.txt 2>/dev/null

If found, plan to include Database Patterns section.

**Step 4: Detect API frameworks**

```bash
grep -E 'sqlalchemy|django|psycopg|asyncpg' pyproject.toml requirements.txt 2>/dev/null

若找到，计划添加「数据库模式」部分。

**步骤4：检测API框架**

```bash

Go

Go

grep -E 'gorilla/mux|gin-gonic|chi|echo|fiber|go-swagger' go.mod 2>/dev/null
grep -E 'gorilla/mux|gin-gonic|chi|echo|fiber|go-swagger' go.mod 2>/dev/null

Node.js

Node.js

grep -E '"express"|"fastify"|"koa"|"hono"|"next"' package.json 2>/dev/null
grep -E '"express"|"fastify"|"koa"|"hono"|"next"' package.json 2>/dev/null

Python

Python

grep -E 'fastapi|flask|django|starlette' pyproject.toml requirements.txt 2>/dev/null

If found, plan to include API Patterns section.

**Step 5: Build enrichment plan**

Compile a list of which optional CLAUDE.md sections to include and which domain-specific patterns to apply:
Enrichment Plan:
  • sapcc Go conventions (if sapcc imports detected)
  • OpenStack/Gophercloud patterns (if gophercloud detected)
  • Error Handling section (if Go, Rust, or explicit error patterns)
  • Database Patterns section (if DB driver detected)
  • API Patterns section (if API framework detected)
  • Configuration section (if non-trivial config detected)

**GATE**: Enrichment sources identified. Domain-specific patterns loaded (or explicitly noted as not applicable). Enrichment plan documented. Proceed ONLY when gate passes.

---
grep -E 'fastapi|flask|django|starlette' pyproject.toml requirements.txt 2>/dev/null

若找到，计划添加「API模式」部分。

**步骤5：制定增强计划**

编译可选CLAUDE.md部分的列表，以及要应用的领域特定模式：
增强计划：
  • sapcc Go规范（若检测到sapcc导入）
  • OpenStack/Gophercloud模式（若检测到gophercloud）
  • 错误处理部分（若为Go、Rust或存在明确错误模式）
  • 数据库模式部分（若检测到数据库驱动）
  • API模式部分（若检测到API框架）
  • 配置部分（若存在非平凡配置）

**检查点**：已识别增强源。已加载领域特定模式（或明确记录为不适用）。已记录增强计划。仅当检查点通过后，方可继续。

---

Phase 3: GENERATE

阶段3：GENERATE（生成）

Goal: Load template, fill sections from scan results and enrichment, write CLAUDE.md.
Step 1: Load template
Read 
${CLAUDE_SKILL_DIR}/references/CLAUDEMD_TEMPLATE.md
for the output structure.
Step 2: Fill required sections
Fill all 6 required sections from Phase 1 scan results:
Section 1 -- Project Overview: Use project name from config file and a description derived from README.md (first paragraph), go.mod module path, or package.json description. List 3-5 key concepts extracted from directory names and core module names.
Section 2 -- Build and Test Commands: Use ONLY commands found in Makefile, package.json scripts, or equivalent. Format as table. Include "check everything" command prominently. Include single-test and package-test commands.
Section 3 -- Architecture: Map directory structure from Phase 1 Step 4. Identify key components by reading entry points and core modules. Use absolute directory descriptions, not guesses.
Section 4 -- Code Style: Document linter config findings, import ordering (from reading actual source files), naming conventions (from actual code patterns), and tooling that enforces style.
Section 5 -- Testing Conventions: Document test framework, assertion library, mocking approach, file naming pattern, and integration test requirements from Phase 1 Step 5.
Section 6 -- Common Pitfalls: Derive from actual codebase analysis. Examples of real pitfalls:
  • Build tool quirks (e.g., "Makefile is managed by go-makefile-maker -- do not edit directly")
  • Dependency gotchas (e.g., "gophercloud v2 migration incomplete -- some packages still use v1")
  • Test requirements (e.g., "integration tests require PostgreSQL running locally")
  • Config requirements (e.g., "OS_AUTH_URL must be set for any OpenStack operation")
Do NOT invent pitfalls. If nothing notable was found, include 1-2 based on the build system (e.g., "run make check before committing").
Step 3: Fill optional sections
Based on the Phase 2 enrichment plan, fill applicable optional sections:
  • Error Handling: For Go repos, document wrapping conventions found in source. For sapcc repos, include 
    fmt.Errorf("...: %w", err)
    pattern and note error checking tools from linter config.
  • Database Patterns: Document the driver/ORM, migration tool, and key query patterns found in source.
  • API Patterns: Document the framework, auth mechanism, and response format found in source.
  • Configuration: Document config source (env vars, files, flags), key variables from 
    .env.example
    , and override precedence.
Step 4: Apply domain enrichment
For sapcc Go repos (detected in Phase 2 Step 1), integrate these patterns into the relevant sections:
In Code Style, add:
  • Anti-over-engineering: prefer simple, readable solutions over clever abstractions
  • Scope 
    must.Return
    to init functions and test helpers only
  • Error wrapping: always add context with 
    fmt.Errorf("during X: %w", err)
In Testing Conventions, add:
  • Table-driven tests as the default pattern
  • Relevant assertion libraries detected in go.mod
In Common Pitfalls, add:
  • go-makefile-maker manages the Makefile (if detected)
  • Any sapcc-specific patterns found in the codebase
Step 5: Write output
Write the completed CLAUDE.md (or CLAUDE.md.generated) to the output path determined in Phase 1 Step 1.
If writing to 
CLAUDE.md.generated
, also show the user a summary diff:
bash
diff CLAUDE.md CLAUDE.md.generated 2>/dev/null || echo "New file created"
GATE: CLAUDE.md written. All required sections populated with project-specific content (no placeholders). Optional sections populated based on enrichment plan. Output path is correct. Proceed ONLY when gate passes.
目标：加载模板，从扫描结果和增强内容中填充部分，写入CLAUDE.md。
步骤1：加载模板
读取
${CLAUDE_SKILL_DIR}/references/CLAUDEMD_TEMPLATE.md
获取输出结构。
步骤2：填充必填部分
从第一阶段的扫描结果中填充所有6个必填部分：
部分1——项目概述：使用配置文件中的项目名称，以及从README.md（第一段）、go.mod模块路径或package.json描述中提取的项目描述。列出从目录名称和核心模块名称中提取的3-5个关键概念。
部分2——构建和测试命令：仅使用从Makefile、package.json脚本或等效文件中找到的命令。以表格形式展示。突出显示「全量检查」命令。包含单测试和包测试命令。
部分3——架构：基于第一阶段步骤4的目录结构梳理结果。通过读取入口点和核心模块识别关键组件。使用绝对目录描述，而非猜测。
部分4——代码风格：记录代码检查器配置的发现结果、导入顺序（从实际源码中读取）、命名规范（从实际代码模式中提取）以及强制执行风格的工具。
部分5——测试规范：记录从第一阶段步骤5中获取的测试框架、断言库、Mock方式、文件命名模式和集成测试要求。
部分6——常见陷阱：从实际代码库分析中提取。真实陷阱示例：
  • 构建工具的特殊用法（例如：「Makefile由go-makefile-maker管理——请勿直接编辑」）
  • 依赖陷阱（例如：「gophercloud v2迁移未完成——部分包仍使用v1」）
  • 测试要求（例如：「集成测试要求本地运行PostgreSQL」）
  • 配置要求（例如：「任何OpenStack操作都必须设置OS_AUTH_URL」）
请勿编造陷阱。若未发现显著陷阱，可基于构建系统添加1-2个（例如：「提交前运行make check」）。
步骤3：填充可选部分
基于第二阶段的增强计划，填充适用的可选部分：
  • 错误处理：对于Go仓库，记录源码中发现的错误包装规范。对于sapcc仓库，包含
    fmt.Errorf("...: %w", err)
    模式，并记录代码检查器配置中的错误检查工具。
  • 数据库模式：记录驱动/ORM、迁移工具以及源码中发现的关键查询模式。
  • API模式：记录框架、认证机制以及源码中发现的响应格式。
  • 配置：记录配置源（环境变量、文件、flag）、
    .env.example
    中的关键变量以及覆盖优先级。
步骤4：应用领域增强
对于第二阶段步骤1中检测到的sapcc Go仓库，将以下模式集成到相关部分：
在代码风格部分添加：
  • 反过度设计：优先选择简单、易读的解决方案，而非巧妙的抽象
  • must.Return
    仅用于初始化函数和测试助手
  • 错误包装：始终使用
    fmt.Errorf("during X: %w", err)
    添加上下文
在测试规范部分添加：
  • 默认使用表驱动测试模式
  • go.mod中检测到的相关断言库
在常见陷阱部分添加：
  • Makefile由go-makefile-maker管理（若检测到）
  • 代码库中发现的任何sapcc特定模式
步骤5：写入输出
将完成的CLAUDE.md（或CLAUDE.md.generated）写入第一阶段步骤1中确定的输出路径。
若写入到
CLAUDE.md.generated
，还需向用户展示差异摘要：
bash
diff CLAUDE.md CLAUDE.md.generated 2>/dev/null || echo "New file created"
检查点：已写入CLAUDE.md。所有必填部分已填充项目专属内容（无占位符）。已基于增强计划填充可选部分。输出路径正确。仅当检查点通过后，方可继续。

Phase 4: VALIDATE

阶段4：VALIDATE（验证）

Goal: Verify the generated CLAUDE.md is accurate, complete, and free of generic filler.
Step 1: Verify all paths exist
Extract every file path and directory path mentioned in the generated CLAUDE.md. Check each one:
bash
undefined
目标：验证生成的CLAUDE.md准确、完整且无通用填充内容。
步骤1：验证所有路径存在
提取生成的CLAUDE.md中提到的每个文件路径和目录路径，逐一检查：
bash
undefined

For each path mentioned in the output

对于输出中提到的每个路径

test -e "<path>" && echo "OK: <path>" || echo "MISSING: <path>"

If any path is missing, fix or remove the reference.

**Step 2: Verify all commands parse**

Extract every command mentioned in the generated CLAUDE.md. Check each one exists:

```bash
test -e "<path>" && echo "OK: <path>" || echo "MISSING: <path>"

若任何路径不存在，修复或移除相关引用。

**步骤2：验证所有命令可执行**

提取生成的CLAUDE.md中提到的每个命令，逐一检查是否存在：

```bash

For each command mentioned (e.g., "make lint")

对于每个提到的命令（例如："make lint"）

Verify the tool exists

验证工具存在

which <tool> 2>/dev/null || echo "MISSING: <tool>"
which <tool> 2>/dev/null || echo "MISSING: <tool>"

For Makefile targets, verify the target exists

对于Makefile目标，验证目标存在

grep -q '^<target>:' Makefile 2>/dev/null || echo "MISSING TARGET: <target>"

If a command references a missing tool or target, fix or remove it.

**Step 3: Check for remaining placeholders**

Search the output for placeholder patterns:

```bash
grep -E '\{[^}]+\}|TODO|FIXME|TBD|PLACEHOLDER' <output_file>
If any placeholders remain, fill them from repo analysis or remove the containing section.
Step 4: Check for generic filler
Search the output for banned generic phrases:
- "use meaningful variable names"
- "write clean code"
- "follow best practices"
- "ensure code quality"
- "maintain consistency"
- "keep it simple"
- "write tests"
- "handle errors properly"
If any generic filler is found, replace with project-specific content or remove.
Step 5: Report summary
Display a validation report:
CLAUDE.md Generation Complete
==============================
Output: <path>
Sections: <count> required + <count> optional
Paths verified: <count> OK, <count> fixed
Commands verified: <count> OK, <count> fixed
Placeholders: <count> (should be 0)
Generic filler: <count> (should be 0)

Domain enrichment applied:
- <enrichment 1>
- <enrichment 2>

Next steps:
- Review the generated file
- If CLAUDE.md.generated: compare with existing CLAUDE.md and merge manually
- Use /claude-md-improver to refine further
GATE: All paths resolve. All commands verified. No placeholders remain. No generic filler detected. Validation report displayed.
grep -q '^<target>:' Makefile 2>/dev/null || echo "MISSING TARGET: <target>"

若命令引用的工具或目标不存在，修复或移除相关内容。

**步骤3：检查剩余占位符**

在输出中搜索占位符模式：

```bash
grep -E '\\{[^}]+\\}|TODO|FIXME|TBD|PLACEHOLDER' <output_file>
若存在任何占位符，从仓库分析中填充内容或移除包含占位符的部分。
步骤4：检查通用填充内容
在输出中搜索禁用的通用表述：
- "use meaningful variable names"
- "write clean code"
- "follow best practices"
- "ensure code quality"
- "maintain consistency"
- "keep it simple"
- "write tests"
- "handle errors properly"
若发现任何通用填充内容，替换为项目专属内容或移除。
步骤5：报告摘要
展示验证报告：
CLAUDE.md生成完成
==============================
输出路径：<path>
部分数量：<count>个必填 + <count>个可选
路径验证：<count>个通过，<count>个已修复
命令验证：<count>个通过，<count>个已修复
占位符：<count>个（应为0）
通用填充内容：<count>个（应为0）

已应用的领域增强：
- <增强项1>
- <增强项2>

下一步：
- 审核生成的文件
- 若为CLAUDE.md.generated：与现有CLAUDE.md对比并手动合并
- 使用/claude-md-improver进一步优化
检查点：所有路径可解析。所有命令已验证。无剩余占位符。未检测到通用填充内容。已展示验证报告。

Examples

示例

Example 1: Go sapcc Repository

示例1：Go sapcc仓库

User says: "generate claude.md" Actions:
  1. SCAN: Detect go.mod, parse Makefile targets (
    make build
    , 
    make check
    , 
    make lint
    ), map 
    cmd/
    , 
    internal/
    , 
    pkg/
    directories, find 
    _test.go
    files with 
    testify
    assertions
  2. DETECT: Find 
    github.com/sapcc
    imports in go.mod, load sapcc conventions (anti-over-engineering, error wrapping, go-makefile-maker)
  3. GENERATE: Fill template with Go-specific content, add sapcc enrichment to Code Style and Testing sections, include error handling section
  4. VALIDATE: Verify all 
    internal/
    paths exist, confirm 
    make check
    target exists in Makefile, no placeholders Result: CLAUDE.md with sapcc-aware conventions, real Makefile commands, verified paths
用户指令："generate claude.md" 操作：
  1. SCAN：检测到go.mod，解析Makefile目标（
    make build
    , 
    make check
    , 
    make lint
    ），梳理
    cmd/
    , 
    internal/
    , 
    pkg/
    目录，找到使用
    testify
    断言的
    _test.go
    文件
  2. DETECT：在go.mod中找到
    github.com/sapcc
    导入，加载sapcc规范（反过度设计、错误包装、go-makefile-maker）
  3. GENERATE：使用Go专属内容填充模板，在代码风格和测试部分添加sapcc增强内容，包含错误处理部分
  4. VALIDATE：验证所有
    internal/
    路径存在，确认Makefile中存在
    make check
    目标，无占位符 结果：生成包含sapcc感知规范、真实Makefile命令、已验证路径的CLAUDE.md

Example 2: Node.js/TypeScript Project

示例2：Node.js/TypeScript项目

User says: "create a claude.md for this repo" Actions:
  1. SCAN: Detect 
    package.json
    , extract npm scripts (
    npm test
    , 
    npm run build
    , 
    npm run lint
    ), map 
    src/
    , 
    tests/
    directories, find 
    .test.ts
    files with vitest
  2. DETECT: Find express in dependencies, plan API Patterns section, no domain enrichment
  3. GENERATE: Fill template with TypeScript content, include API patterns (Express routes, middleware), testing conventions (vitest, co-located tests)
  4. VALIDATE: Verify all paths, confirm npm scripts exist, no generic filler Result: CLAUDE.md with actual npm commands, Express API patterns, vitest testing conventions
用户指令："create a claude.md for this repo" 操作：
  1. SCAN：检测到
    package.json
    ，提取npm脚本（
    npm test
    , 
    npm run build
    , 
    npm run lint
    ），梳理
    src/
    , 
    tests/
    目录，找到使用vitest的
    .test.ts
    文件
  2. DETECT：在依赖中找到express，计划添加API模式部分，无领域增强
  3. GENERATE：使用TypeScript内容填充模板，包含API模式（Express路由、中间件）、测试规范（vitest、同目录测试）
  4. VALIDATE：验证所有路径，确认npm脚本存在，无通用填充内容 结果：生成包含真实npm命令、Express API模式、vitest测试规范的CLAUDE.md

Example 3: Existing CLAUDE.md

示例3：已存在CLAUDE.md的情况

User says: "generate claude.md" Actions:
  1. SCAN: Find existing CLAUDE.md, set output to 
    CLAUDE.md.generated
    , continue analysis
  2. DETECT: Standard detection, no special domain
  3. GENERATE: Write to 
    CLAUDE.md.generated
  4. VALIDATE: Show diff between existing and generated, suggest using claude-md-improver to merge Result: CLAUDE.md.generated alongside existing file, with diff for comparison
用户指令："generate claude.md" 操作：
  1. SCAN：找到已存在的CLAUDE.md，设置输出路径为
    CLAUDE.md.generated
    ，继续分析
  2. DETECT：标准检测，无特殊领域
  3. GENERATE：写入到
    CLAUDE.md.generated
  4. VALIDATE：展示现有文件与生成文件的差异，建议使用claude-md-improver合并 结果：在现有文件旁生成CLAUDE.md.generated，并提供差异对比

Error Handling

错误处理

Error: No Build System Detected

错误：未检测到构建系统

Cause: No Makefile, package.json scripts, Taskfile, or other build configuration found. Solution: Generate a minimal CLAUDE.md documenting only what can be verified (directory structure, language, test patterns). Note prominently in the Build and Test Commands section: "No build system detected -- add build commands manually." Continue with all other phases.
原因：未找到Makefile、package.json脚本、Taskfile或其他构建配置。 解决方案：生成极简版CLAUDE.md，仅记录可验证的内容（目录结构、语言、测试模式）。在构建和测试命令部分显著标注：「未检测到构建系统——请手动添加构建命令。」继续执行所有其他阶段。

Error: CLAUDE.md Already Exists

错误：CLAUDE.md已存在

Cause: Repository already has a CLAUDE.md (root or 
.claude/
directory). Solution: Write output to 
CLAUDE.md.generated
. Show diff between existing and generated files. Suggest using 
claude-md-improver
to merge improvements. Never overwrite without explicit user confirmation.
原因：仓库中已存在CLAUDE.md（根目录或
.claude/
目录）。 解决方案：将输出写入
CLAUDE.md.generated
。展示现有文件与生成文件的差异。建议使用
claude-md-improver
合并改进内容。绝不在未获得用户明确确认的情况下覆盖现有文件。

Error: Unknown Language

错误：未知语言

Cause: No recognized language indicator files in the repository root. Solution: Produce a language-agnostic CLAUDE.md focusing on directory structure, Makefile targets (if present), and any README content. Note the gap: "Language could not be auto-detected -- add language-specific sections manually."
原因：仓库根目录中无识别的语言标识文件。 解决方案：生成与语言无关的CLAUDE.md，重点关注目录结构、Makefile目标（若存在）和README内容。标注缺失信息：「无法自动检测语言——请手动添加语言专属部分。」

Anti-Patterns

反模式

Anti-Pattern 1: Generic Filler Content

反模式1：通用填充内容

What it looks like: "Write clean, maintainable code" or "Follow best practices for error handling" in the generated CLAUDE.md. Why wrong: Generic advice wastes context tokens and provides zero project-specific signal. Claude already knows generic best practices. Do instead: Only include facts derived from actual repo analysis. "Error wrapping uses 
fmt.Errorf('during %s: %w', action, err)
pattern (see 
internal/api/handler.go
)" is useful. "Handle errors properly" is not.
表现：生成的CLAUDE.md中出现「编写清晰、可维护的代码」或「遵循错误处理最佳实践」这类表述。 错误原因：通用建议会浪费上下文token，且无法提供任何项目专属信息。Claude已经知晓通用最佳实践。 正确做法：仅包含从仓库实际分析中获取的事实。「错误包装使用
fmt.Errorf('during %s: %w', action, err)
模式（见
internal/api/handler.go
）」这类内容是有用的。而「正确处理错误」则毫无价值。

Anti-Pattern 2: Guessing Commands

反模式2：猜测命令

What it looks like: Writing 
go test ./...
without checking the Makefile, or 
npm test
without reading package.json scripts. Why wrong: The Makefile may wrap 
go test
with flags, coverage, or race detection. Using the wrong command teaches Claude to skip project-specific tooling. Do instead: Read the Makefile (or equivalent) first. Use the project's canonical commands. If 
make check
exists, document 
make check
, not the raw tool invocations.
表现：未检查Makefile就写入
go test ./...
，或未读取package.json脚本就写入
npm test
。 错误原因：Makefile可能会为
go test
添加flag、覆盖率或竞态检测。使用错误命令会让Claude跳过项目专属工具。 正确做法：优先读取Makefile（或等效文件）。使用项目的标准命令。若存在
make check
，则记录
make check
，而非原始工具调用。

Anti-Pattern 3: Copying README Verbatim

反模式3：直接复制README内容

What it looks like: Pasting the README's project description, installation steps, or usage examples into CLAUDE.md. Why wrong: README is for GitHub visitors (humans browsing the repo). CLAUDE.md is for Claude sessions (AI working in the codebase). Different audiences need different information. README covers "what is this and how to install it." CLAUDE.md covers "how to work effectively in this codebase." Do instead: Extract relevant facts from README (project purpose, key concepts) but reframe for Claude's needs. Skip installation guides, badges, and user-facing documentation.
表现：将README中的项目描述、安装步骤或使用示例直接粘贴到CLAUDE.md中。 错误原因：README是给GitHub访客（浏览仓库的人类）看的。CLAUDE.md是给Claude会话（在代码库中工作的AI）看的。不同受众需要不同信息。README涵盖「这是什么以及如何安装」。CLAUDE.md涵盖「如何在该代码库中高效工作」。 正确做法：从README中提取相关事实（项目用途、关键概念），但需为Claude的需求重新组织语言。跳过安装指南、徽章和面向用户的文档。

Anti-Pattern 4: Including IDE Setup

反模式4：包含IDE设置

What it looks like: Adding VS Code extensions, editor config, or debugging launch configurations to CLAUDE.md. Why wrong: CLAUDE.md is read by Claude, not by editors. IDE setup belongs in README or CONTRIBUTING.md. Do instead: Document CLI commands for linting, formatting, and testing. These are what Claude actually uses.
表现：在CLAUDE.md中添加VS Code扩展、编辑器配置或调试启动配置。 错误原因：CLAUDE.md是给Claude读的，而非编辑器。IDE设置应放在README或CONTRIBUTING.md中。 正确做法：记录用于linting、格式化和测试的CLI命令。这些才是Claude实际会使用的内容。

Anti-Rationalization

反合理化

Domain-Specific Rationalizations

领域特定的合理化借口

RationalizationWhy It's WrongRequired Action
"I know this is a Go project, I can fill in standard Go patterns"Standard patterns may not match this project's conventionsRead actual source files before writing any section
"The README has a good description, I'll use that"README is for humans, CLAUDE.md is for Claude sessionsExtract facts, reframe for Claude's context
"No Makefile, but 
go build
is obvious"		The project may use a custom build script or task runnerDocument the gap, don't guess commands
"This section is optional, I'll skip the analysis"Optional sections still require evidence if includedEither analyze properly or omit the section entirely
"The paths probably exist, no need to check each one"Probably != verified. One broken path undermines trustCheck every path with 
test -e
"Generic advice is better than nothing"Generic advice is worse than nothing -- it wastes tokensLeave section out rather than fill with filler
合理化借口错误原因要求操作
「我知道这是Go项目，我可以填充标准Go模式」标准模式可能与该项目的规范不符在编写任何部分前，先读取实际源码
「README有很好的描述，我直接用它」README是给人类看的，CLAUDE.md是给Claude会话看的提取事实，为Claude的上下文重新组织语言
「没有Makefile，但
go build
是显而易见的」		项目可能使用自定义构建脚本或任务运行器记录该缺失信息，不要猜测命令
「这个部分是可选的，我可以跳过分析」可选部分若要包含，仍需有证据支持要么正确分析，要么完全省略该部分
「这些路径可能存在，没必要逐一检查」可能存在不等于已验证。一个无效路径会破坏信任使用
test -e
检查每个路径
「通用建议总比没有好」通用建议比没有更糟——它会浪费token省略该部分，而非填充通用内容

References

参考资料

This skill uses these shared patterns:
  • Anti-Rationalization - Prevents shortcut rationalizations
本Skill使用以下共享模式：
  • Anti-Rationalization - 防止走捷径的合理化借口

Reference Files

参考文件

  • ${CLAUDE_SKILL_DIR}/references/CLAUDEMD_TEMPLATE.md
    : Template structure for generated CLAUDE.md files with required and optional sections
  • Official Anthropic 
    claude-md-management:claude-md-improver
    : Companion skill for improving existing CLAUDE.md files (use after generation for refinement)
  • ${CLAUDE_SKILL_DIR}/references/CLAUDEMD_TEMPLATE.md
    ：生成CLAUDE.md文件的模板结构，包含必填和可选部分
  • 官方Anthropic 
    claude-md-management:claude-md-improver
    ：用于改进现有CLAUDE.md文件的配套Skill（生成后可使用它进一步优化）

Companion Skills

配套Skill

  • go-sapcc-conventions
    : Domain-specific patterns for sapcc Go repositories (loaded during Phase 2 enrichment)
  • codebase-overview
    : Deeper codebase exploration when CLAUDE.md generation needs more architectural context
  • go-sapcc-conventions
    ：sapcc Go仓库的领域特定模式（在第二阶段增强时加载）
  • codebase-overview
    ：当CLAUDE.md生成需要更多架构上下文时，用于深度探索代码库",