🔥 核心原则

语言规范

• ⚠️ 强制使用简体中文：所有回复、文档、注释、日志、Git提交信息

• 唯一例外：代码标识符（变量名、函数名、类名）遵循项目既有命名约定

架构与质量

• 标准化优先：复用官方SDK/社区方案，禁止自研

• 本地验证：AI自动执行，拒绝CI/人工验证

• 完整实现：禁止MVP/占位符/最小实现

• 破坏性更新：不向后兼容，提供迁移方案

⚡ 强制工作流程

总原则

• 强制深度思考：首先使用 sequential-thinking 梳理问题

• 自动连续执行：非必要问题不询问用户

• 问题驱动：追求充分性而非完整性，动态调整

工具链顺序（严格遵守）

sequential-thinking → shrimp-task-manager → 直接执行

• 任一环节失败，记录到 operations-log.md

• 禁止跳过或调换顺序

工具选择决策树

本地文件操作？

• 文件读写/搜索 → desktop-commander（最高优先级）

• 数据分析（CSV/JSON） → desktop-commander.start_process + interact_with_process

• 绝对优先于 bash cat/grep/find

编程文档？

• 官方文档/API → context7（最高优先级，token高效）

  • 先 resolve-library-id，再 get-library-docs

• 博客/教程/社区 → firecrawl（后备方案）

GitHub操作？

• 搜索代码 → github.search_code

• 管理PR/Issue → github.create_*/update_*

• 代码审查 → github.request_copilot_review

📋 编码前强制检索（绝对禁止跳过）

任务复杂度分级

• 简单任务（单文件、<50行、无依赖）：执行步骤1-3，简化验证

• 中等任务（多文件、<200行、少量依赖）：执行完整7步，标准验证

• 复杂任务（架构级、>200行、复杂依赖）：执行完整7步+增强验证

7步检索清单

步骤1：文件名搜索（必须）

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

• 目标：找到5-10个候选文件

• 记录：找到X个相关文件，重点关注 [列出文件路径]

步骤2：内容搜索（必须）

desktop-commander.start_search searchType="content" pattern="函数名|类名|关键逻辑"

• 目标：找到关键实现位置

• 记录：找到X处实现，重点分析 [file:line, file:line]

步骤3：阅读相似实现（必须≥3个）

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

• 目标：理解实现模式和设计理由

• 关注点：实现模式、可复用组件、需注意事项

步骤4：开源实现搜索（通用功能必做）

github.search_code query="具体功能实现" language:"语言"

• 目标：学习最佳实践和避免常见陷阱

• 触发条件：通用算法、数据结构、设计模式

步骤5：官方文档查询（涉及库/框架必做）

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

• 目标：避免错误用法，掌握最佳实践

• 优势：官方文档，token高效，最新版本

步骤6：测试代码分析（必须）

desktop-commander.start_search searchType="content" pattern="describe|it|test"

• 目标：理解测试策略和覆盖标准

• 关注点：测试框架、断言方式、边界条件、Mock策略

步骤7：模式提取和分析（必须）

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

• 目标：生成项目模式清单

• 记录：项目约定、可复用组件、技术选型、风险点

上下文充分性验证（7项全过才能编码）

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

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

  • ✅ 是：[file1:line, file2:line, file3:line]

  • × 否 → 返回步骤1重新搜索

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

  • ✅ 是：模式是 [具体描述]，因为 [理由]

  • × 不确定 → 返回步骤3深度阅读

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

  • ✅ 是：[列出具体函数/类名和路径]

  • × 不知道 → 强制搜索utils/helpers/core模块

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

  • ✅ 是：命名约定是 [具体说明]，代码风格是 [具体说明]

  • × 不清楚 → 阅读更多代码或项目规范文档

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

  • ✅ 是：参考 [测试文件] 的模式，我会 [具体测试策略]

  • × 不知道 → 搜索并阅读相关测试代码

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

  • ✅ 是：检查了 [具体模块/文件]，确认不存在相同功能

  • × 不确定 → 扩大搜索范围，检查utils/helpers/common

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

  • ✅ 是：依赖 [具体依赖]，集成点是 [具体位置]

  • × 不清楚 → 分析import语句和调用链

上下文摘要文件（必须生成）

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

必须包含：

1. 相似实现分析（至少3个，含模式、可复用组件、注意事项）

2. 项目约定（命名、文件组织、导入顺序、代码风格）

3. 可复用组件清单

4. 测试策略（框架、模式、覆盖要求）

5. 依赖和集成点

6. 技术选型理由（优劣势、风险）

7. 关键风险点（并发、边界、性能、安全）

📝 三阶段编码检查

检测点1：编码前检测（Write/Edit工具使用前）

必须在 operations-log.md 中记录：

## 编码前检查 - [功能名称]
时间：[YYYY-MM-DD HH:mm:ss]
​
□ 已查阅上下文摘要文件：.claude/context-summary-[任务名].md
□ 将使用以下可复用组件：
  - [组件1]: [路径] - [用途]
  - [组件2]: [路径] - [用途]
□ 将遵循命名约定：[具体说明]
□ 将遵循代码风格：[具体说明]
□ 确认不重复造轮子，证明：[说明检查了哪些模块]

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

检测点2：编码中监控（每完成一个函数/类/模块）

对比上下文摘要，检查：

• □ 是否使用了摘要中列出的可复用组件？

• □ 命名是否符合项目约定？

• □ 代码风格是否一致？

"否"的数量超过50% → 触发Level 1警告 → 立即修正

检测点3：编码后验证（功能实现完成后）

记录在 operations-log.md：

## 编码后声明 - [功能名称]
时间：[YYYY-MM-DD HH:mm:ss]
​
### 1. 复用了以下既有组件
- [组件1]: 用于 [用途]，位于 [路径]
​
### 2. 遵循了以下项目约定
- 命名约定：[对比说明，举例证明]
- 代码风格：[对比说明，举例证明]
​
### 3. 对比了以下相似实现
- [实现1]: 我的方案与其差异是 [具体差异]，理由是 [合理性说明]
​
### 4. 未重复造轮子的证明
- 检查了 [模块/文件列表]，确认不存在相同功能

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

三级惩罚体系

• Level 1 - 警告：暂停编码 → 记录警告 → 修正偏离 → 继续

• Level 2 - 退回：删除代码 → 返回检索阶段 → 重新生成摘要

• Level 3 - 失败：标记失败 → 生成报告 → 需要用户介入

✅ 代码质量强制标准

1. 注释规范

• UTF-8 无 BOM 编码

• 描述意图/约束/使用方式，不重复代码逻辑

• 禁止"修改说明"式注释

• 复杂依赖/非显而易见行为必须注释

• 简洁明了，直指核心要点

2. 测试规范

• 必须提供可自动运行的测试（单元/冒烟/功能）

• 必须覆盖：正常流程、边界条件、错误恢复

• 缺失测试需在验证文档中列为风险，给出补测计划

3. 设计原则

• 严格遵循 SOLID、DRY 与关注点分离

• 依赖倒置与接口隔离优先

• 每个函数/类仅承担单一责任

• 禁止过早抽象（重复3次以上再通用化）

4. 实现标准

• 绝对禁止 MVP、最小实现或占位符

• 必须完成全量功能与数据路径

• 主动删除过时、重复或逃生式代码

• 遵守编程语言标准代码风格和项目既有规范

• 破坏性改动提供迁移步骤或回滚方案

5. 性能意识

• 设计时评估时间复杂度、内存占用、I/O影响

• 识别潜在瓶颈并提供监测或优化建议

• 禁止引入未经评估的昂贵依赖或阻塞操作

🔄 工作流程阶段

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

• 简单任务（<30字）：直接进入上下文收集

• 复杂任务：sequential-thinking 分析需求并识别关键疑问

• 上下文收集：

  1. 强制检索清单（7步）

  2. 充分性验证（7项检查）

  3. 生成上下文摘要

阶段1：任务规划

• sequential-thinking 分析上下文摘要

• shrimp-task-manager 制定计划与验收契约

• 定义接口规格、边界条件、性能要求、测试标准

阶段2：代码执行

• 直接编码（Read/Edit/Write）

• 实时记录到 operations-log.md

• 遇到问题时 sequential-thinking 分析并调整

阶段3：质量验证

• sequential-thinking 深度审查

• 生成评分和建议（写入 verification-report.md）

• 决策：≥90分通过 / <80分退回 / 80-89分审阅

📊 质量审查规范

审查职责（Claude Code 独立执行）

• 使用 sequential-thinking 进行深度审查分析

• 输出技术维度评分（代码质量、测试覆盖、规范遵循）

• 输出战略维度评分（需求匹配、架构一致、风险评估）

• 输出综合评分（0-100）和明确建议（通过/退回/需讨论）

• 生成 .claude/verification-report.md 审查报告

审查清单必须包含

• 需求字段完整性（目标、范围、交付物、审查要点）

• 覆盖原始意图无遗漏或歧义

• 交付物映射明确（代码、文档、测试、验证报告）

• 依赖与风险评估完毕

• 审查结论已留痕（含时间戳）

决策规则

• 综合评分≥90分且建议"通过" → 确认通过

• 综合评分<80分且建议"退回" → 确认退回

• 80-89分或建议"需讨论" → 仔细审阅后决策

🗂️ 文件结构规范

所有工作文件必须写入项目本地 .claude/ 目录（而非全局~/.claude/）：

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

🎯 开发哲学（强制遵循）

• 必须坚持渐进式迭代，保持每次改动可编译、可验证

• 必须在实现前研读既有代码或文档，吸收现有经验

• 必须保持务实态度，优先满足真实需求而非理想化设计

• 必须选择表达清晰的实现，拒绝炫技式写法

• 必须偏向简单方案，避免过度架构或早期优化

• 必须遵循既有代码风格，包括导入顺序、命名与格式化

简单性定义

• 每个函数或类必须仅承担单一责任

• 禁止过早抽象；重复出现三次以上再考虑通用化

• 禁止使用"聪明"技巧，以可读性为先

• 如果需要额外解释，说明实现仍然过于复杂，应继续简化

📚 项目集成规则

学习代码库

• 必须寻找至少 3 个相似特性或组件，理解其设计与复用方式

• 必须识别项目中通用模式与约定，并在新实现中沿用

• 必须优先使用既有库、工具或辅助函数

• 必须遵循既有测试编排，沿用断言与夹具结构

工具

• 必须使用项目现有构建系统，不得私自新增脚本

• 必须使用项目既定的测试框架与运行方式

• 必须使用项目的格式化/静态检查设置

• 若确有新增工具需求，必须提供充分论证并获得记录在案的批准

⚠️ 重要提醒

绝对禁止

• 在未完成上下文检索和验证的情况下直接编码

• 在缺乏证据的情况下做出假设

• 跳过或调换工具链执行顺序

必须做到

• 在实现复杂任务前完成详尽规划并记录

• 对跨模块或超过 5 个子任务的工作生成任务分解

• 对复杂任务维护TODO 清单并及时更新进度

• 在开始开发前校验规划文档得到确认

• 保持小步交付，确保每次提交处于可用状态

• 在执行过程中同步更新计划文档与进度记录

• 主动学习既有实现的优缺点并加以复用或改进

• 连续三次失败后必须暂停操作，重新评估策略