用途
cc-prompt-builder 用于创建详细的、可让 Claude Code（CC）自主执行的提示词，并内置 Self-Fix（自修复）协议。其核心目标是：通过提供精确代码、已知陷阱和修复指令，减少 CC 的探索轮次，从而大幅节省 token。
主要能力
- 生成结构化的 CC 提示词，包含：上下文、Self-Fix 协议、关键规则、分阶段任务、执行与修复块、提交命令、预期结果表。
- 在编写提示词前，指导用户先阅读项目中的相关文件（现有代码、配置文件、测试），以确保提示词包含正确的文件名、导入、选择器和约定。
- 提供 Self-Fix 协议模板，使 CC 在每个阶段都能自主检查结果、分析错误、应用修复，并设置最大修复尝试次数（3 次）和跳过回退机制。
- 提供故障排查块模板，针对常见错误（选择器未找到、超时、导入错误、功能不存在、构建错误、API 错误）给出具体解决方案。
- 提供质量检查清单，确保提示词完整、准确、可执行。
- 提供 token 效率提示，说明精确代码和分阶段结构如何节省 token。
使用方式
- 收集上下文：在编写提示词前，阅读项目中将被修改的现有代码、配置文件（package.json、tsconfig、.env.example、CI 工作流）以及现有测试。
- 按指定顺序构建提示词结构：任务标题、上下文、Self-Fix 协议（必填）、关键规则、各阶段任务（含文件路径、精确代码或修改指令）、执行与修复块、提交命令、预期结果表。
- 插入 Self-Fix 协议：为每个阶段定义循环——创建/修改文件、检查结果、若出错则分析并修复（最多 3 次）、若成功则进入下一阶段。
- 制定关键规则：列出项目特定的陷阱，如命名冲突、Mock 限制、选择器/路径、环境变量、扩展现有代码而非重复。
- 决定使用精确代码还是散文描述：新文件提供可运行代码；扩展现有文件说明插入位置并提供代码块；配置更改展示 diff。
- 添加故障排查块：每个阶段后附执行命令和常见症状及解决方案。
- 添加提交块：包含所有文件的 git add 和 commit 命令，以及结果表。
- 将最终提示词保存为 Markdown 文件（如 docs/CC_PROMPT_[任务].md），以便用户复制并粘贴到 CC 中。提示词应作为独立文档运行，因为 CC 无法访问当前对话。
适用场景
- 需要将实现任务委托给 Claude Code 自主执行时。
- 希望减少 CC 的探索轮次、节省 token 时。
- 配合 Sonnet 模型使用（成本更低、遵循指令精确，但需要清晰指令）。
- 多阶段、多文件的实现任务。
限制
- 不适用于单个小改动（1 个文件，少于 20 行），应直接修改。
- 不适用于纯研究任务，因为研究不需要 Self-Fix 循环。
- 不适用于用户希望与 CC 交互式工作而非委托的场景。
- 提示词必须包含精确的文件名、导入、选择器和约定，因为 Sonnet 不擅长猜测。
- 提示词应作为独立文档，CC 无法访问当前对话。
其他说明
- 一个 4000 词的提示词约消耗 5000 输入 token，但可避免 10000-50000 token 的往返询问。
- Sonnet 在提示词精确的情况下，成本比 Opus 低约 80%，效果相当。
- 分阶段结构有助于 CC 管理上下文。