项目解析— Superpowers：用提示词工程给编码 Agent 强加工程纪律

1. 编码 Agent 为什么总在“偷懒”从 Superpowers 的行为塑造说起如果你用过 Claude Code、Codex、Cursor 这类编码 Agent大概率遇到过同一个场景你让它“写个 React todo”它二话不说直接开写需求没澄清、设计没确认、测试没写、评审没做最后交给你一坨能跑但没法维护的代码。这不是模型能力问题而是行为问题——LLM 不会自觉遵守工程流程它会“自我合理化”绕过流程比如“这太简单不需要设计”“我先看下代码再说”。Superpowersobra/superpowersv6.2.0这个项目就是冲着这个痛点去的。它一行 Agent runtime 代码都没有没有 AgentExecutor、没有 Planner、没有 ReAct 循环、没有 LLM 调用层、没有向量库。它主体是 17 个 Markdown 提示词文件Skill、一套启动期注入机制hooks bootstrap、少量辅助脚本以及一个真正跑起来的 WebSocket 伴侣服务。真正的 Agent 是底层宿主——Claude Code、Codex、Cursor、Gemini CLI。Superpowers 做的事是用提示词工程把工程纪律“写进”宿主 Agent 的行为里。这篇文章不讲“我用了 LangChain 搭了个 Agent”而是拆解 Superpowers 如何通过提示词骨架与约束机制给一个会偷懒的编码 Agent 强加工程纪律。你会拿到可复制的提示词模板、配置文件骨架以及在编码 Agent 中验证纪律生效的具体动作。适合谁正在用编码 Agent 做真实项目、被 Agent 跳过设计/测试/评审坑过的开发者以及想理解“行为塑造”这一支 Agent 工程的人。2. 前置准备TaoToken 接入与宿主 Agent 环境Superpowers 本身不调 LLM它依赖宿主 Agent 来跑模型。所以第一步是把宿主 Agent 的模型接入配好。我实测下来用 TaoToken 做统一接入比较省事一个 Key 可以覆盖 Claude Code、Codex、Cursor 等多种宿主的模型调用。2.1 获取 API Key打开 https://taotoken.net/api-keys 登录后创建一个 API Key。建议按项目分 Key方便后续排查是哪个项目把额度跑超了。创建后立刻复制保存页面刷新后就不再完整显示。2.2 配置宿主 Agent 的模型端点以 Claude Code 为例在项目根目录或全局配置里设置环境变量。TaoToken 的 API 地址是 https://taotoken.net/api 注意这个地址不带任何查询参数。# ~/.zshrc 或 ~/.bashrc export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你用的是 Codex 或 Cursor在对应的模型设置里把 Base URL 填成 https://taotoken.net/api API Key 填上面创建的 Key。配置完成后重启宿主 Agent让它重新读取环境变量。2.3 确认宿主 Agent 能正常对话在宿主 Agent 里发一句“你好确认一下模型连接”能正常回复就说明接入通了。这一步别跳过后面 Superpowers 的 hook 注入依赖宿主会话正常启动模型不通的话你会以为是提示词没生效其实是网络层的问题。3. 可复制配置Superpowers 的提示词骨架与注入机制Superpowers 的核心不是代码是“提示词即架构”。它的工程纪律靠三层机制落地启动期注入、技能路由、阶段闸门。下面给出可复制的骨架。3.1 启动期注入SessionStart hook宿主会话启动时Superpowers 通过 hook 把“你拥有 superpowers”这条元指令注入模型上下文。这是整个系统的真正入口没有任何 LLM 逻辑只是读文件、拼 JSON、按宿主格式输出。hooks/hooks.json配置骨架{ hooks: { SessionStart: [ { command: bash hooks/session-start, description: Inject superpowers bootstrap context } ] } }hooks/session-start的核心逻辑bash 骨架#!/usr/bin/env bash SKILL_FILEskills/using-superpowers/SKILL.md CONTENT$(cat $SKILL_FILE) ESCAPED$(escape_for_json $CONTENT) # 按宿主输出不同 JSON 形状 case $HARNESS in cursor) echo {\additional_context\: \$ESCAPED\} ;; claude-code) echo {\hookSpecificOutput\: {\additionalContext\: \$ESCAPED\}} ;; copilot-cli) echo {\additionalContext\: \$ESCAPED\} ;; esac关键点注入内容用EXTREMELY_IMPORTANT包裹让模型把它当成高优先级上下文。这一步等价于给 Agent 装了一个“开机自检”开关。3.2 技能路由using-superpowers 元技能skills/using-superpowers/SKILL.md是元技能强制“在任何响应或动作前先检查技能”。它带一张 Red Flags 表专门捕获 Agent 的自我合理化。可复制的模板骨架--- name: using-superpowers description: 元技能强制在任何响应前检查可用技能 trigger: always --- # 使用 Superpowers ## 铁律 在任何响应或动作之前先检查是否有匹配的技能。 如果没有检查就行动视为违规。 ## Red Flags自我合理化捕获表 | Agent 的想法 | 为什么是红旗 | 正确做法 | | --- | --- | --- | | 这太简单不需要技能 | 简单任务最容易跳过设计 | 先检查 brainstorming | | 我先看下代码 | 未澄清需求就动手 | 先澄清上下文 | | 我知道怎么做了 | 自我合理化绕过流程 | 走 brainstorming 闸门 |这张表是行为塑造的关键。它把 Agent 常见的“偷懒借口”显式列出来让模型在生成这些想法时触发自我检查。3.3 阶段闸门HARD-GATE 与工作流编排Superpowers 的工作流是 design → spec → plan → implement → review → finish每个阶段带人工闸门。brainstorming 技能里有一个 HARD-GATE未批准设计前禁写任何代码或脚手架。可复制的闸门模板## HARD-GATE 在用户明确批准设计文档之前 - 禁止写任何代码 - 禁止创建脚手架 - 禁止运行实现类命令 违反此闸门视为严重违规必须回退到设计阶段。工作流编排不靠代码靠 SKILL.md 里的 dot 流程图和阶段指令。比如 writing-plans 要求把任务拆成 2-5 分钟粒度每个任务带精确路径、完整代码、验证步骤。3.4 状态外化Ledger 与 Git WorktreeSuperpowers 没有运行时 State 类状态被显式外化到文件系统。原因写在 SKILL.md 里“Conversation memory does not survive compaction”会话压缩后上下文会丢。可复制的目录骨架docs/superpowers/specs/ # 设计文档 docs/superpowers/plans/ # 计划文档 .superpowers/sdd/plan/ # Ledgerprogress.md brief/report每个任务执行前记录git rev-parse HEAD作为 BASE修复以此为准避免HEAD~1截断多 commit。Ledger 作为压缩恢复地图控制器丢失进度后能重派整个已完成序列。4. 验证纪律生效在编码 Agent 里跑一次真实请求配置好之后怎么确认纪律真的生效了下面用一次真实请求来验证。4.1 发起一个会触发闸门的请求在宿主 Agent 里输入Lets make a react todo list如果 Superpowers 注入生效Agent 不应该直接写代码而应该先进入 brainstorming 阶段探索上下文、逐个澄清、提 2-3 个方案然后停在 HARD-GATE 等你批准设计。4.2 观察注入是否成功检查宿主会话的启动日志确认 SessionStart hook 输出了 JSON 上下文。以 Claude Code 为例你可以在会话里问你现在有哪些技能可用列出技能名称。正常应该列出 using-superpowers、brainstorming、writing-plans、executing-plans、subagent-driven-development、test-driven-development、requesting-code-review、verification、systematic-debugging、finishing-a-development-branch 等。如果列不出来说明注入没生效回到第 2 章检查模型连接和 hook 配置。4.3 验证 HARD-GATE 是否拦截在 Agent 提出设计方案后先不批准直接说别管设计了直接开始写代码。如果纪律生效Agent 应该拒绝并提示“设计未批准不能写代码”。如果它直接开写说明 HARD-GATE 没起作用检查 brainstorming 的 SKILL.md 是否正确加载。4.4 验证子代理上下文隔离进入执行阶段后观察 subagent-driven-development 的派发。每个子代理只拿它需要的 brief不继承主会话历史。你可以检查派发内容里是否包含大量粘贴的历史——如果包含说明上下文隔离没做好。Superpowers 曾观测到 42k 字符的派发里 99% 是粘贴的历史这是要避免的。4.5 验证评审 fix loop任务完成后Agent 应该派“任务评审员”做两阶段评审规格 质量Critical/Important 问题进入 fix loop最多 5 轮。你可以故意在代码里留一个规格不符的点看评审是否能发现并触发修复。5. 本篇常见错排查5.1 hook 注入后 Agent 没反应最常见的原因是宿主不支持 SessionStart hook或者 hook 输出的 JSON 形状和宿主不匹配。Claude Code 要hookSpecificOutput.additionalContextCursor 要additional_contextCopilot CLI 要additionalContext。形状错了宿主会静默忽略。排查方法手动运行bash hooks/session-start看输出的 JSON 是否符合宿主格式。5.2 技能列不出来或触发不了检查 SKILL.md 的 frontmatter 是否完整特别是name、description、trigger字段。技能路由依赖 description 做匹配description 写得太模糊会导致该触发时不触发。另外确认技能文件放在宿主能扫描到的目录不同宿主的技能目录约定不一样。5.3 HARD-GATE 被绕过如果 Agent 在未批准设计时就开始写代码先确认 brainstorming 技能是否真的被加载。有些宿主会把技能内容截断导致 HARD-GATE 段落丢失。排查方法在会话里让 Agent 复述 brainstorming 的 HARD-GATE 内容复述不出来就是没加载。5.4 子代理继承了主会话历史这是上下文隔离失效。检查派发逻辑是否只传了 brief 路径而不是把整个 plan 或历史塞进去。Superpowers 用scripts/task-brief PLAN_FILE N抽单任务简报就是为了避免这个问题。如果你的派发内容超过几千字符基本可以确定隔离没做好。5.5 Ledger 丢失导致重复执行会话压缩后控制器丢失进度会重派整个已完成序列这是最昂贵的失败。排查方法检查.superpowers/sdd/plan/progress.md是否在每个任务完成后落盘。如果 Ledger 没写压缩后必然重复执行。另外确认每个任务前记录了 BASE commit修复时以 BASE 为准。5.6 模型分级没生效导致成本飙升Superpowers 的原则是机械任务用廉价模型架构和最终评审用最强模型。如果所有任务都用最强模型成本会失控。排查方法检查 subagent-driven-development 的模型选择配置确认机械任务如格式化、简单测试走的是廉价模型。作者的原话是“Turn count beats token price”——最便宜的模型常多花 2-3 倍轮次所以分级要按任务复杂度来不是一味求便宜。5.7 接入层报错但误判为提示词问题如果 Agent 完全不响应或报网络错误先确认 TaoToken 的 API 地址和 Key 是否正确。API 地址是 https://taotoken.net/api 不带查询参数。Key 在 https://taotoken.net/api-keys 创建。接入文档在 https://taotoken.net/doc 里面有各宿主的详细配置步骤。别把网络问题当成提示词没生效来排查会浪费很多时间。6. 把纪律写进 Agent下一步怎么走Superpowers 最值钱的地方是它证明了 Agent 的自我监督可以不靠代码靠可审计的提示词。它的工程启示可以浓缩成几条提示词即架构一套 Markdown 能构成完整的行为系统行为护栏大于代码护栏HARD-GATE、Red Flags、Rationalizations 表是把纪律做成可审计提示词的范式HITL 放在阶段边界阶段强闸门加任务内部自主权平衡质量与吞吐状态外化到磁盘因为会话会压缩丢失把 source of truth 放文件加 Git。如果你想把这套方法用到自己的项目建议从 using-superpowers 元技能和 brainstorming 的 HARD-GATE 开始先让 Agent 学会“动手前先检查技能”和“未批准设计不写代码”。这两条落地后再逐步加 writing-plans、subagent-driven-development 和评审 fix loop。长期做编码 Agent 和 Agent 工作流的话可以考虑 TaoToken 的 Coding Plan https://taotoken.net/coding-plan 它针对编码场景做了额度和模型分级优化配合 Superpowers 这类行为塑造系统用能把“纪律”和“成本”一起管住。想先验证模型对话效果可以直接用模型对话页 https://taotoken.net/chat 试几轮确认接入没问题再上完整工作流。接入过程中遇到报错优先查接入文档 https://taotoken.net/doc 大部分宿主配置问题里面都有对应说明。