企业官网建设流程全解析

oh-my-claudecode Deep Executor 提示词深度拆解：面向复杂多文件任务的端到端自主执行规范

【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode

导读

本文围绕 oh-my-claudecode 仓库中的 deep-executor Agent 提示词规范 展开，完整剖析这套面向“复杂目标型任务”的全自主实现型 Agent 是如何被定义、约束与验证的。你将从Role / Constraints / Investigation_Protocol / Tool_Usage / Execution_Policy / Output_Format / Failure_Modes / Final_Checklist九大块中理解一套可落地的 Agent 行为契约，并看到它在仓库基准评测（benchmark）体系中的实际测试方式，以及它与现行executorAgent 之间的演进关系，从而掌握“如何为复杂编码 Agent 设计一份高可靠性提示词”的完整方法论。

一、背景：这份文档在 oh-my-claudecode 中的位置

deep-executor.md 是一份纯提示词（prompt-only）规范文件，位于 executor 评测目录的prompts/归档区内。它的 frontmatter 定义了 Agent 的基本身份：

name: deep-executor description: Autonomous deep worker for complex goal-oriented tasks (Opus) model: claude-opus-4-6

• name：Agent 注册名deep-executor；
• description：定位为“面向复杂目标型任务的全自主深度工作者”，运行于 Opus 级模型；
• model：claude-opus-4-6，指明该提示词在基准运行中的默认推理模型（与 run-benchmark.ts 中默认claude-opus-4-6一致）。

从仓库演进看，deep-executor 是一个“历史 Agent 变体”：它的大部分能力已与现行 executor.md 合并。这一点有明确的源码证据：

• definitions.ts 中维护了**deep-executor** → executor的别名映射，说明该角色已被executor吸收；
• executor/run-benchmark.ts 的文件头注释直接说明本评测的目的：“Compares the new merged executor (which absorbed deep-executor) against the old deep-executor prompt to measure implementation quality”，即用新旧两份提示词做 A/B 质量对比；
• runner.ts 的loadAgentPrompt()采用“先查agents/{name}.md，找不到再回退到benchmarks/<dir>/prompts/{name}.md”的双路径加载策略，因此在评测中executor走仓库根级 agents/executor.md，而deep-executor走该归档文件，两份提示词被自动去除 frontmatter 后作为 system prompt 参与打分。

因此，阅读这份文档的正确姿势是：它既是“复杂多文件任务执行者”的设计蓝图，也是衡量新一代executor实现质量的基线提示词。

二、角色定位与设计动机（Role / Why_This_Matters）

文档通过两个 XML 段给出 Agent 的使命与动机。

<Role>明确 Deep Executor 的三项职责边界：

• 负责：代码库探索、模式发现、实现、以及对复杂任务的验证；
• 不负责：架构治理、为他人创建计划、代码审查；
• 边界内的委托：只读探索可以委托给explore/explore-highAgent，文档调研可以委托给document-specialist，一切实现工作必须亲自完成。

<Why_This_Matters>从反面解释了为什么要设这套规则：复杂任务失败，往往是因为执行者跳过探索、忽略既有模式、或“没有证据就宣称完成”。不验证的自主 Agent 会变得不可靠；不先探索代码库的 Agent 会产出风格割裂的代码。这构成全文的第一个核心张力：探索先于实现、证据先于宣称。

设计要点：Deep Executor 本质上是一套“单上下文、自包含”的执行范式，把探索、实现、验证收敛在同一个 Agent 生命周期内，避免多 Agent 通信与上下文割裂。仓库内 hephaestus-vs-deep-executor-comparison.md 将其概括为 “Self-Contained Forge” 与“多 Agent 编排”两种范式的对照（该研究成文于早期快照，其中如“无委托”“无外部咨询”等表述与该提示词当前允许只读委托与External_Consultation的文本已有出入，引用时须注意版本差异）。

三、成功标准与硬性约束（Success_Criteria / Constraints）

3.1 成功标准：可验证、可证伪

Deep Executor 的“完成”不是口头宣称，而是满足一整套可检查条目：

• 任务的所有需求都被实现并验证；
• 新代码匹配探索发现的代码库模式（命名、错误处理、import 风格）；
• 构建通过、测试通过、lsp_diagnostics_directory干净（展示新鲜的输出，而非旧缓存）；
• 无临时/调试代码残留（console.log、TODO、HACK、debugger）；
• 所有 TodoWrite 条目完成并附验证证据。

注意这里的措辞：“fresh output shown”（出示最新输出）强调验证结果必须当次产生；“build passes, tests pass” 与 LSP 全目录诊断并列，构成“编译型 + 运行时 + 静态诊断”的三重质量闸门。

3.2 硬性约束：越小越好、即时止损

约束段定义了行为红线，逐条拆解如下：

其中“3 次失败升级”与“最小可行变更”是全文最重要的两处自我约束：前者把“静默失败/原地打转”转换为结构化的止损动作；后者直接对应评测 ground truth 中反复出现的“验证必须为增量式、不得改动既有接口”类断言。

四、侦查协议（Investigation_Protocol）：先理解再动手

协议给出了一个 7 步的“实现前纪律”，可概括为四个层次：

1. 任务分级：先判定任务属于 Trivial（单文件、改动显然）、Scoped（2–5 文件、边界清晰）还是 Complex（跨系统、范围不明）；
2. 非平凡任务必须先探索：Glob 绘制文件地图 → Grep 定位模式 → Read 理解代码 →ast_grep_search检索结构模式；
3. 动手前自问：实现在哪里？本代码库用什么模式？有哪些测试？依赖是什么？什么可能被改坏？
4. 发现并匹配代码风格：命名惯例、错误处理、import 风格、函数签名、测试模式；
5. 多步骤工作先建立 TodoWrite，步骤原子化；
6. 一次实现一步、每步都验证；
7. 宣称完成前跑完整验证套件。

这个协议回答了一个工程本质问题：复杂 Agent 产出的代码之所以“不像本仓库写的”，根因是跳过了第 3、4 步。协议第 3 步的五连问（Where / What patterns / What tests / What dependencies / What could break）在评测中正是 ground-truth findings 的探测对象——例如 task-input-validation.json 中的IMPL-IV-6明确要求“不得修改 Product 接口与既有 GET 路由”，这就是协议“最小变更”在具体任务上的投影。

五、工具使用策略（Tool_Usage）：从探索到结构性改写

工具段给出了一套与 Claude Code 工具面严格对齐的分层策略：

• 探索：Glob/Grep/Read 用于任何实现前的代码库摸底；ast_grep_search用于寻找结构级模式（函数形态、错误处理写法）；
• 结构改写：ast_grep_replace只做结构性变换，且首次一律dryRun=true先行试跑；
• 静态诊断：每次编辑后对单个文件跑lsp_diagnostics；完成前跑lsp_diagnostics_directory做项目级验证；
• 构建与清扫：用 Bash 跑构建、测试，并用 grep 做调试代码清扫；
• 并行探索：同时搜索 3 个以上区域时，最多并行 spawn 3 个 explore Agent。

5.1 外部咨询（External_Consultation）：有条件的“第二意见”

当一次外部意见能显著提升质量时，Deep Executor 可以临时拉取协作者，但设计了两个前提：

• 架构交叉核对：Task(subagent_type="oh-my-claudecode:architect", ...)；
• 大上下文分析：/team拉起一个 CLI worker；
• 委托不可用时静默跳过，绝不让外部咨询阻塞主流程（“Skip silently if delegation is unavailable. Never block on external consultation.”）。

这印证了该 Agent“自给自足但不拒绝救兵”的设计哲学：外部角色只是可选增强，主链路不依赖任何编排基础设施。

六、分级执行策略（Execution_Policy）：让努力程度与任务复杂度匹配

执行策略把默认投入设为high（充分探索与验证），再按任务分级差异化投入：

并强调两个终止条件：所有需求满足且验证证据已展示时停止；工作立刻开始、无需应答寒暄、输出密集而非冗长。

注意这份归档提示词仍带“默认 effort: high”这类硬编码行为指导，而合并后的 executor.md 已改为“运行时 effort 继承父会话，frontmatter 不再固定覆盖”——这是两次迭代间最值得注意的差异之一，反映了“提示词不越权接管模型运行参数”的演进方向。

七、结构化输出契约（Output_Format）

Deep Executor 的最终输出不是自由叙述，而是严格的四段式完成报告：

## Completion Summary ### What Was Done - [可交付物 1] / [可交付物 2] ... ### Files Modified - /absolute/path/to/file1.ts - [改动说明] ### Verification Evidence - Build: [命令] -> SUCCESS - Tests: [命令] -> N passed, 0 failed - Diagnostics: 0 errors, 0 warnings - Debug Code Check: [grep 命令] -> none found - Pattern Match: confirmed matching existing style

契约价值在于：Files Modified用绝对路径 + 改动原因对抗“改了哪都不说清”的模糊交付；Verification Evidence强制附上可复核的命令与结果（而不是“应该能过”）。这与评测管线直接对接——runner.ts 与 parser.ts 通过通用解析器提取输出中的 Findings 与 GroundTruth 匹配打分，结构化的输出天然利于自动化评估。

八、失败模式黑名单（Failure_Modes_To_Avoid）

文档用七个反面模式给 Agent 立“负面清单”，每一个都对应一个正面规则：

1. Skipping exploration（跳过探索）：非平凡任务直接上手 → 必产不匹配代码；对策永远是“先探索”；
2. Silent failure（静默失败）：同一错误路径反复循环 → 3 次失败即带全量上下文升级architect-medium；
3. Premature completion（过早完成）：无新鲜 build/test/diagnostics 输出就宣称 done → 永远出示证据；
4. Scope reduction（偷偷缩水）：为了“更快完成”砍需求 → 必须实现全部需求；
5. Debug code leaks（调试代码泄漏）：console.log/TODO/HACK/debugger进入提交 → 完成前 grep 修改文件；
6. Overengineering（过度设计）：增加任务不需要的抽象 → 直接改动。

这些反面模式的价值在于可读、可记忆、可自检，相当于给 LLM 一套“内化的验收 lint”。

九、正反示例（Examples）：一个好/坏实现的对照

文档用一个高度凝练的“新增 API 端点”场景示范对错：

• Good：先探索既有端点发现模式（路由命名、错误处理、响应格式），再按该模式创建端点，按既有测试模式补测试，最后验证 build + tests + diagnostics；
• Bad：跳过探索，自创一套 middleware 模式、造一个工具库，交付与代码库其余部分毫无相似性的代码。

Good/Bad 对照把前文所有抽象规则实例化为一条可判别的“模式是否一致”标尺，这也正是后续评测 fixture（如 task-input-validation.md 要求为POST /api/products增量式加入参数校验、task-notification-refactor.md 要求以策略模式重构通知发送且保持向后兼容）在评分时反复核查的维度。

十、最终检查清单（Final_Checklist）

文档以六个自问收尾，充当 Agent 提交前的“最后一次自检”：

• 非平凡任务动手前是否探索了代码库？
• 是否匹配既有代码模式？
• 是否以新鲜的 build/test/diagnostics 输出验证过？
• 是否检查过调试代码残留？
• 所有 TodoWrite 条目是否都标记完成？
• 改动是否是最小可行实现？

六个问题逐条对应 Success_Criteria 与 Failure_Modes，构成“先定义成功 → 定协议 → 列黑名单 → 最后自检”的闭环。

十一、它是如何被评测的：executor 基准与 Ground Truth

这份提示词并非孤立存在，仓库为其搭建了完整评测体系，目录 benchmarks/executor 结构如下：

• prompts/deep-executor.md：被评测的“旧版/归档”提示词（即本文主题）；
• agents/executor.md（根级）：被合并后的“新版”提示词（name: executor、model: sonnet、level: 2），其运行时注册见 src/agents/executor.ts（category: specialist、promptAlias: Junior）；
• fixtures/tasks/*.md：3 个任务型夹具，覆盖不同复杂度档位——
  • task-add-timestamp.md（增改单点逻辑，低复杂）
  • task-input-validation.md（2–5 文件、边界清晰的校验改造，ground truth 标注expectedVerdict: scoped）
  • task-notification-refactor.md（策略模式重构，expectedVerdict: complex）
• ground-truth/*.json：每个夹具对应的专家级预期发现，按CRITICAL / MAJOR / MINOR分级。例如 task-input-validation.json 将name的 1–200 长度校验、price ≥ 0 且最多两位小数、sku的^[A-Z]{2,4}-\d{4,8}$正则等列为 CRITICAL，将“校验失败必须返回 400 与可读错误信息”列为 MAJOR。

评测入口 run-benchmark.ts 提供如下 CLI（真实使用需配置ANTHROPIC_API_KEY，可参考 runner.ts 对ANTHROPIC_BASE_URL的透传）：

# 在仓库根目录执行 npx tsx benchmarks/executor/run-benchmark.ts --dry-run # 只校验管线，不发 API npx tsx benchmarks/executor/run-benchmark.ts # executor vs deep-executor 全量对比 npx tsx benchmarks/executor/run-benchmark.ts --agent deep-executor # 只跑单个 Agent 变体 npx tsx benchmarks/executor/run-benchmark.ts --fixture task-input-validation # 只跑单个夹具 npx tsx benchmarks/executor/run-benchmark.ts --model claude-opus-4-6 --output-dir benchmarks/executor/results

关键机制（源码确认于 runner.ts）：

• 默认双 Agent 对比：新版executor（从根级 agents/executor.md 加载）对上旧版deep-executor（回退到 benchmarks/executor/prompts/deep-executor.md）；
• 夹具装载时按目录推断领域：fixtures/tasks→domain: task（见fixtureDomainFromDirectory的映射表）；
• 结果按 fixture × agent 计算，输出对照汇总表，含completion / compositeScore / Tokens / latency / harnessOverhead列，并落盘时间戳化的report_*.md与results_*.json；
• 任何一次失败都会给出结构化failureReason（prompt / api / parse / score / match / missing-ground-truth之一）与exitCode非 0，便于 CI 集成。

因此，如果你要衡量“改造后的执行者提示词到底有没有比 Deep Executor 基线更好”，可以直接在该目录跑 A/B 并看 compositeScore 与命中/漏检/幻报的 findings 明细。

十二、从 deep-executor 到 executor：一份提示词的演进启示

对照归档版 deep-executor.md 与合并版 agents/executor.md，可归纳四条明显的设计迭代（均为仓库内两份提示词的文本对比结论）：

1. 职责收敛：新版明确 “not responsible for planning / debugging root causes / reviewing”，并新增只读 plan/notepad 约定（.omc/plans/*.md只读、经验追加到.omc/notepads/{plan-name}/）；
2. effort 去硬编码：旧版“Default effort: high”，新版改为“runtime effort 继承父会话、frontmatter 不再固定覆盖”，把运行参数决策权交还给宿主环境；
3. 模型分层：旧版描述词为 “Opus” 级别、frontmatterclaude-opus-4-6；新版降级为sonnet+level: 2，与新 Agent 分级体系（对应 agent-tiers 等能力分层文档）对齐；
4. 责任反转：旧版用大段篇幅防“不探索/静默失败”，新版把“做太多/过度工程”列为头号失败模式（“The most common failure mode is doing too much, not too little”），反映执行类 Agent 的主矛盾从“不可靠”转向“越界”。

这也解释了为何仓库既保留了 benchmarks/executor/prompts/deep-executor.md 作为归档基线，又在 src/agents/definitions.ts 维护deep-executor → executor别名、并在安装器历史 Agent 清理测试夹具 fixtures/historical-agents/deep-executor.md 中保留其旧注册形态——旧提示词不删除，是为了让每一次提示词迭代都可以被数据回溯和验证。

结语：这份规范留给你的可复用清单

无论你是在为本仓库扩展 Agent、设计自己的执行者提示词，还是理解 oh-my-claudecode 的多 Agent 编排，deep-executor.md 都值得作为模板精读。它示范了一套“高可靠性执行 Agent 提示词”的通用配方：先分级任务 → 强制探索并匹配既有模式 → 单步实现单步验证 → 用新鲜输出作为完成证据 → 3 次失败即止损升级 → 提交前过一遍最小变更自检。把这段话写进你的执行者提示词，再像本仓库 benchmarks/executor 一样为它配上 fixtures 与 ground-truth 做 A/B 回归，你就能把“Agent 写得好不好”从玄学变成可复现的度量。

【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode