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)
- 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 , 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 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
, 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）、中的关键变量以及覆盖优先级。
步骤4：应用领域增强
对于第二阶段步骤1中检测到的sapcc Go仓库，将以下模式集成到相关部分：
在代码风格部分添加：
- 反过度设计：优先选择简单、易读的解决方案，而非巧妙的抽象
- 仅用于初始化函数和测试助手
- 错误包装：始终使用
fmt.Errorf("during X: %w", err)
在测试规范部分添加：
- 默认使用表驱动测试模式
- go.mod中检测到的相关断言库
在常见陷阱部分添加：
- Makefile由go-makefile-maker管理（若检测到）
- 代码库中发现的任何sapcc特定模式
步骤5：写入输出
将完成的CLAUDE.md（或CLAUDE.md.generated）写入第一阶段步骤1中确定的输出路径。
bash
diff CLAUDE.md CLAUDE.md.generated 2>/dev/null || echo "New file created"
检查点：已写入CLAUDE.md。所有必填部分已填充项目专属内容（无占位符）。已基于增强计划填充可选部分。输出路径正确。仅当检查点通过后，方可继续。