use-mcp

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本将旧版 Claude /skill-name 引用改写为 $skill-name。
• 任务跟踪要求：执行任何工作流或技能步骤之前，先为所有步骤创建／更新任务跟踪，并随着进度变化保持同步。
• 用户问题提示表示应直接在 Codex 中向用户提问。
• 忽略出现的 Claude 专属模式切换说明。
• 严格执行约定：用户明确调用某项技能时，必须按其说明执行该技能协议。
• 子 Agent 授权：用户调用或 AI 检测到某项技能，且其协议要求使用子 Agent 时，激活该技能即授权为该任务使用所需的 spawn_agent 子 Agent。
• 除非用户事先明确批准偏离，否则不得跳过、重排或合并协议步骤。
• 对于工作流技能，必须明确执行列出的每项子技能步骤，并逐步提供证据。
• 如果当前环境无法运行必需步骤／工具，请停止并在调整方案前询问用户。

Codex 项目参考资料加载（无钩子）

Codex 不会接收基于 Claude 钩子的文档注入。 在编码、规划、调试、测试或审查时，请根据此路由显式打开项目文档。

始终阅读：

• docs/project-config.json（项目专属路径、命令、模块以及工作流／测试设置）
• docs/project-reference/docs-index-reference.md（指向完整 docs/project-reference/* 目录的路由）
• docs/project-reference/lessons.md（始终适用的防护规则和反模式）

根据情况阅读的文档：

• 后端／CQRS／API／领域／实体变更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
• 前端／UI／样式／设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 规范／测试用例规划或 TC 映射：feature-docs-reference.md
• 集成测试实施／审查：integration-test-reference.md
• E2E 测试实施／审查：e2e-test-reference.md
• 代码审查／审计工作：code-review-rules.md，并根据变更文件阅读相关领域文档

不要盲目阅读所有文档。请从 docs-index-reference.md 开始，然后仅打开与任务相关的文件。

快速摘要

目标： 利用 MCP（Model Context Protocol）服务工具扩展 Claude 的能力。

工作流：

1. 发现——列出可用的 MCP 工具及其功能
2. 选择——为任务选择合适的工具
3. 执行——使用正确的参数运行 MCP 工具

关键规则：

• 尝试使用工具之前，先检查可用的 MCP 服务
• 对于内置工具不具备的能力，使用 MCP 工具
• 妥善处理 MCP 工具错误，并采用备用方案

保持审慎。运用批判性思维和顺序思维。每项声明都必须有可追溯的证据和置信度百分比（Idea 应高于 80%）。

通过 Gemini CLI 执行 MCP 操作，以节省上下文预算。

执行步骤

1. 通过 Gemini CLI 执行任务（使用标准输入管道支持 MCP）：

   # 重要：使用标准输入管道，而非 -p 标志（已弃用，会跳过 MCP 初始化）
   echo "$ARGUMENTS. Return JSON only per GEMINI.md instructions." | gemini -y -m gemini-2.5-flash
   

2. 回退到通用子 Agent（如果 Gemini CLI 不可用）：

   • 使用 general-purpose 子 Agent 发现并执行工具
   • 如果子 Agent 遇到 mcp-management 技能脚本的问题，使用 mcp-builder 技能修复
   • 仅重复使用现有的 mcp-management／mcp-builder 脚本——不得创建任何新脚本
   • 子 Agent 只能使用 MCP 工具（如有）来完成此任务
   • 如果子 Agent 找不到合适的工具，只需将情况报告给主 Agent，然后继续下一步

重要说明

• 务必注意使用 stdin 管道传递——已弃用的 -p 标志会跳过 MCP 初始化
• 使用 -y 标志自动批准工具执行
• 自动加载 GEMINI.md：Gemini CLI 会自动从项目根目录加载 GEMINI.md，强制使用仅含 JSON 的响应格式
• 可解析的输出：响应为结构化 JSON：{"server":"name","tool":"name","success":true,"result":<data>,"error":null}

反面模式（切勿使用）

# BROKEN - deprecated -p flag skips MCP server connections!
gemini -y -m gemini-2.5-flash -p "..."

---

[IMPORTANT] 开始前务必使用任务跟踪，将所有工作拆分为小任务——包括为每个文件读取操作创建任务。这可以防止因文件过长而丢失上下文。对于简单任务，AI 务必询问用户是否要跳过。

防止 AI 犯错——每项任务都应避免以下失败模式：

删除前检查下游引用。 删除组件会导致文档和代码连锁过时。删除前先梳理所有引用文件。 根据实际代码验证 AI 生成的内容。 AI 会捏造 API、类名和方法签名。记录或引用之前，务必使用 grep 确认其确实存在。 编辑后追踪完整依赖链。 更改定义时，容易遗漏由其派生的下游变量和使用方。务必追踪完整链路。 验证正确性时追踪所有代码路径。 确认代码存在不等于确认代码会执行。务必追踪提前退出、错误分支和条件跳过，而不仅仅是正常路径。 调试时，修复前先问“责任在谁？” 追踪问题究竟在调用方（数据错误）还是被调用方（处理错误）。在负有责任的层级修复，切勿只修补症状出现的位置。 假设现有值是有意设置的——修改前先问原因。 更改任何常量、限制、标志或模式之前，先阅读注释、检查 git blame，并查看周边代码。 验证所有受影响的输出，而不只是第一个。 涉及多个技术栈的更改，需要验证每一项输出。一个检查通过不代表所有检查都通过。 优先整体排查——避免陷入最近注意到的问题。 调查任何故障时，先列出所有前置条件（配置、环境变量、数据库名称、端点、DI 注册、数据前置条件），再逐一根据证据验证，然后再提出任何代码层面的假设。 精准修改——应用差异测试。 修复 bug 时，每一行改动都必须能直接追溯到该 bug。不要顺手调整格式或改进相邻代码。增强任务：实现改进并明确说明。 编码前先指出歧义——不要默默做出选择。 如果请求存在多种解释，应列出每种解释、估算工作量并询问。切勿擅自假设用户需要所有记录、基于文件的方案或更复杂的路径。

批判性思维——运用批判性思维和顺序思维。每项主张都必须有可追溯的证据，且置信度须高于 80% 才能采取行动。 防止幻觉： 切勿把猜测当作事实；每项主张都要引用来源，坦诚承认不确定性，自行检查输出是否有误，独立交叉核对，并对自己的判断保持怀疑——毫无证据的确信是所有幻觉的根源。

务必注意运用批判性思维——每项主张都必须有可追溯的证据，且置信度须高于 80% 才能采取行动。防止幻觉：切勿把猜测当作事实。

务必注意遵循 AI 防错原则——优先整体排查，在负有责任的层级修复，编码前指出歧义，并在压缩上下文后重新阅读文件。

收尾提醒

重要，务必注意开始前使用任务跟踪，将工作拆分为小型待办任务 重要，务必注意创建新代码前，在代码库中搜索至少 3 个类似模式 重要，务必注意每项主张都要引用 file:line 证据（置信度须高于 80% 才能采取行动） 重要，务必注意添加最终审查待办任务，以验证工作质量

[TASK-PLANNING] 开始前，分析任务范围，并使用任务跟踪系统地将工作拆分为小型待办任务和子任务。

无钩子提示词协议镜像（自动同步）

来源：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议 — 强制执行，非常重要，必须遵守，至关重要。无论任何理由都不得跳过。

通用可移植性边界： 可复用的技能和协议文本应保持项目中立；项目特定约定应从 docs/project-config.json 和 docs/project-reference/ 中发现。应用 shared/sdd-artifact-contract.md 中的共享 AI-SDD。阅读 docs/project-config.json 和 docs/project-reference/docs-index-reference.md，然后打开其中列出的项目参考文档。只要有此共享上下文和本地文档，任何受支持的 AI 工具均可执行。

1. 检测： 将提示词与工作流目录匹配
2. 分析： 找出最匹配的工作流，并评估自定义步骤组合是否更合适
3. 询问（必需格式）： 直接向用户提问，采用以下结构；但如果用户明确调用了某个工作流/技能，且本地协议将明确调用视为确认，则无需询问：
   • 问题：“你想启用哪个工作流？”
   • 选项 1：“启用 [BestMatch Workflow]（推荐）”
   • 选项 2：“启用自定义工作流：[step1 → step2 → ...]”（附上一句话说明理由）
4. 启用（确认后）： 标准工作流调用 $workflow-start <workflowId>；手动按顺序执行自定义步骤
5. 创建任务： 为工作流的所有步骤创建任务跟踪
6. 执行： 按顺序遵循每个步骤 [CRITICAL-THINKING-MINDSET] 运用批判性思维和顺序思维。每项主张都必须有可追溯的证据，置信度超过 80% 才能采取行动。 反幻觉原则： 切勿将猜测当作事实陈述——每项主张都要引用来源，坦诚承认不确定性，自行检查输出是否有误，独立交叉验证，对自己的判断保持怀疑——毫无证据的确信是所有幻觉的根源。 AI 注意力原则（首因-近因）： 对于较长的提示词/协议，将最关键的 3 条规则同时放在开头和结尾，确保指令在长上下文窗口中仍能得到遵循。 目标驱动执行： 先定义成功标准，持续循环直到验证通过，只有在可观察的检查均通过后才停止。 测试验证意图： 测试必须保护业务规则/不变量，并在受保护的意图遭到破坏时失败，而不是仅仅复现当前行为。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进 — 强制执行。不得跳过。

开始前，将工作拆分成小任务并进行任务跟踪。添加最终任务：“分析 AI 错误与经验教训”。

总结经验教训——仅关注根本原因，不要只修复表象：

1. 指明失败模式（推理/假设错误），而非表象——例如“未阅读源代码就假定 API 存在”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境/代码库？如果不适用，则再抽象一层。
3. 写成通用规则——删去项目特定的名称/路径/类。此规则应适用于任何代码库。
4. 合并：多个错误若共享同一失败模式，则合并为一条经验教训。
5. 复发判断：“如果没有此提醒，这种情况会在未来的会话中再次发生吗？”——不会 → 跳过 $learn。
6. 自动修复判断：“$code-review/$code-simplifier/$security/$lint 能发现这个问题吗？”——能 → 改进审查技能。
7. 两项判断均通过 → 请用户运行 $learn。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建/更新任务跟踪；之后在每个步骤开始/完成时保持同步。