跳至正文
StackBug
返回

CLAUDE.md 开发准则

概览

本文件用于指导在当前仓库内进行的全部开发与文档工作,使输出符合标准、可追溯。

上下文信息要求

语言使用强制规范

🔒 强制验证机制

🤝 质量审查规范

审查职责(Claude Code 独立执行):

审查清单必须包含:

决策规则:

📊 架构优先级

🛡️ 安全性原则

✅ 代码质量强制标准

📝 语言与注释规范

🌐 强制中文使用范围(绝对要求)

所有以下场景必须强制使用简体中文,无任何例外:

唯一例外:代码标识符(变量名、函数名、类名、包名等)遵循项目既有命名约定(通常使用英文)。

📋 注释编写规范

🧪 测试规范

🏗️ 设计原则

💻 实现标准

⚡ 性能意识

🧩 测试思维

🚀 强制工作流程

⚡ 总原则(必须遵循)

🔗 工具链执行顺序(必须)

🔍 信息检索与外部工具集成(必须)

核心原则:

本地文件和数据分析集成(最高优先级)

desktop-commander - 本地文件和进程管理(核心工具):

核心能力:

最佳实践:

注意事项:

编程文档检索优先级(context7 优先)

context7 - 编程库/SDK/API 文档(最高优先级):

调用方式:

  1. 然后调用get-library-docs获取文档(可选 topic 参数聚焦)
  2. 首先调用resolve-library-id获取 Context7 兼容的库 ID

firecrawl - 通用网页检索(通用后备):

调用方式:

  1. firecrawl_map:网站结构发现(探索网站时)
  2. firecrawl_scrape:单页抓取(已知 URL 时)
  3. firecrawl_search:搜索并抓取内容(推荐,自动返回内容)

GitHub 项目协作集成

github - 完整 GitHub 操作:

核心能力:

最佳实践:

工具选择决策树

```

需要本地文件操作? ├─ 文件读写/搜索 → desktop-commander(最高优先级) ├─ 数据分析(CSV/JSON) → desktop-commander.start_process + interact_with_process └─ 进程管理 → desktop-commander.start_process

需要编程相关信息? ├─ 官方文档/API参考 → context7(最高优先级,包含所有技术栈) └─ 最新博客/文章/教程 → firecrawl(通用后备)

需要操作 GitHub? ├─ 搜索代码 → github.searchcode ├─ 读取文件/文档 → github.get_file_contents ├─ 管理 PR/Issue → github.create/update_ └─ 代码审查 → github.request_copilot_review

```

🔍 强制上下文检索机制(编码前必须执行)

绝对禁止:在未完成上下文检索和验证的情况下直接编码。违反者立即终止任务。

📋 编码前强制检索清单(7项必查,复杂度自动分级)

检索强度分级:

完整检索清单:

□ 步骤1:文件名搜索(必须)

```bash

desktop-commander.start_search searchType=“files” pattern=“关键词”

```

□ 步骤2:内容搜索(必须)

```bash

desktop-commander.start_search searchType=“content” pattern=“函数名|类名|关键逻辑” literalSearch=true contextLines=5

```

□ 步骤3:阅读相似实现(必须≥3个)

```bash

Read file_path # 深度阅读至少3个相关文件

```

关注点:

□ 步骤4:开源实现搜索(通用功能必做)

```bash

github.search_code query=“具体功能实现” language:“语言” repo:“优质仓库”

```

□ 步骤5:官方文档查询(涉及库/框架必做)

```bash

context7 resolve-library-id libraryName=“库名” context7 get-library-docs context7CompatibleLibraryID=“库ID” topic=“相关主题”

```

□ 步骤6:测试代码分析(必须)

```bash

desktop-commander.start_search searchType=“content” pattern=“describe|it|test” filePattern=“.spec.|.test.”

```

□ 步骤7:模式提取和分析(必须)

```bash

sequential-thinking # 分析检索结果,提取项目模式

```

记录:

✅ 上下文充分性验证(编码前最后关卡)

必须全部回答”是”且提供具体证据,否则禁止进入编码阶段。

□ 1. 我能说出至少3个相似实现的文件路径吗?

□ 2. 我理解项目中这类功能的实现模式吗?

□ 3. 我知道项目中有哪些可复用的工具函数/类吗?

□ 4. 我理解项目的命名约定和代码风格吗?

□ 5. 我知道如何测试这个功能吗?

□ 6. 我确认没有重复造轮子吗?

□ 7. 我理解这个功能的依赖和集成点吗?

📄 上下文摘要文件(编码前必须生成)

路径:.claude/context-summary-[任务名].md

模板:

```markdown

项目上下文摘要([任务名称])

生成时间:[YYYY-MM-DD HH:mm:ss]

1. 相似实现分析

实现1: src/foo/bar.ts:123-156

实现2: src/baz/qux.ts:78-90

2. 项目约定

3. 可复用组件清单

4. 测试策略

5. 依赖和集成点

6. 技术选型理由

7. 关键风险点

```

🚨 懒惰检测与防护机制

核心原则:研究先于编码,复用优于创造,一致性优于个人偏好。

检测点1:编码前检测(Write/Edit工具使用前)

必须在 operations-log.md 中记录以下检查:

```markdown

编码前检查 - [功能名称]

时间:[YYYY-MM-DD HH:mm:ss]

□ 已查阅上下文摘要文件:.claude/context-summary-[任务名].md □ 将使用以下可复用组件:

```

无法回答任何一项 → 立即终止,返回检索阶段。

检测点2:编码中监控(每完成一个函数/类/模块)

对比上下文摘要,检查:

```markdown

□ 是否使用了摘要中列出的可复用组件? ✅ 是:已使用 [列出] ❌ 否:为什么不用?[合理解释]

□ 命名是否符合项目约定? ✅ 是:对比 [具体例子] ❌ 否:为什么偏离?[合理解释]

□ 代码风格是否一致? ✅ 是:对比 [具体例子] ❌ 否:为什么偏离?[合理解释]

```

“否”的数量超过50% → 触发Level 1警告。

检测点3:编码后验证(功能实现完成后)

完整声明(记录在 operations-log.md):

```markdown

编码后声明 - [功能名称]

时间:[YYYY-MM-DD HH:mm:ss]

1. 复用了以下既有组件

2. 遵循了以下项目约定

3. 对比了以下相似实现

4. 未重复造轮子的证明

```

无法提供完整声明 → 视为懒惰,触发审查。

三级惩罚体系:

Level 1 - 警告(首次检测到懒惰)

  1. 通过复查后继续编码
  2. 重新对比上下文摘要
  3. 要求立即修正偏离部分
  4. 记录警告到 operations-log.md
  5. 立即暂停编码

Level 2 - 强制退回(二次检测到懒惰)

  1. 记录”二次懒惰”到 operations-log.md
  2. 重新通过充分性验证
  3. 重新生成上下文摘要
  4. 强制返回检索阶段
  5. 删除已编写的代码

Level 3 - 任务失败(三次检测到懒惰)

  1. 考虑调整工作流程或提供更多指导
  2. 需要用户介入重新评估任务
  3. 生成失败报告,详细记录懒惰行为
  4. 标记任务为”失败”

📋 文件结构规范

所有任务执行产生的工作文件必须写入项目本地.claude/目录(而非全局~/.claude/):

```

/.claude/ ├── context-summary-[任务名].md ← 上下文摘要(Claude Code 输出) ├── operations-log.md ← 决策和操作记录(Claude Code 输出) └── verification-report.md ← 验证报告(Claude Code 输出)

```

📋 标准工作流 6 步骤(必须执行)

  1. 存储知识
  2. 验证质量
  3. 执行任务
  4. 选择工具
  5. 获取上下文
  6. 分析需求

🔄 研究-计划-实施模式 5 阶段(必须遵循)

  1. 提交:准备交付文档与迁移/回滚方案
  2. 验证:运行测试或验证脚本,记录结果
  3. 实施:根据计划执行并保持小步提交
  4. 计划:制定详细计划与成功标准
  5. 研究:阅读材料、厘清约束,禁止编码

🧭 工作流程阶段定义

阶段0:需求理解与上下文收集

上下文收集:

  1. 生成上下文摘要(.claude/context-summary-[任务名].md
  2. 充分性验证(7项检查,必须全部通过)
  3. 强制检索清单(7步,编码前必做)

阶段1:任务规划

阶段2:代码执行

阶段3:质量验证

根据评分决策:

✋ 任务开始前强制检查(必须执行)

🔄 渐进式上下文收集流程(必须)

核心哲学

步骤1:结构化快速扫描(必须)

执行框架式收集,记录到.claude/context-summary-[任务名].md

现状:现在如何实现?找到1-2个相似案例

技术栈:使用的框架、语言、关键依赖

步骤2:识别关键疑问(必须)

使用 sequential-thinking 分析初步收集和观察报告,识别关键疑问:

步骤3:针对性深挖(按需,建议≤3次)

仅针对高优先级疑问进行深挖:

步骤4:充分性检查(必须)

在进入任务规划前,必须回答充分性检查清单:

决策:

回溯补充机制

允许”先规划→发现不足→补充上下文→完善实现”的迭代:

禁止事项

💡 开发哲学(强制遵循)

简单性定义

🔧 项目集成规则

学习代码库

工具

⚠️ 重要提醒

绝对禁止:

必须做到:

🎯 内容唯一性规则




分享到:

上一篇
从PRD到数据库:一套可执行的数据库设计SOP
下一篇
Spring AI 1.0.3 完全指南:从入门到企业级实践