【免费下载链接】superplaneOpen source factory for one-shot engineering项目地址https://gitcode.com/gh_mirrors/su/superplane点击查看免费下载本文讲解 SuperPlane 中Refine Task任务精炼分析会话的完整设计。它定义了编码 Agent 在执行任务前如何通过研究仓库、提问、评分与撰写规格说明把一段粗糙的草稿任务打磨成一次运行即可交付的构建任务。读完本文你将掌握五步分析流程、Clarity 与 Confidence 双维评分体系的判定标准、规格说明的结构规范以及这套逻辑在仓库中的工程接线方式。一、什么是 Refine Task 分析会话SuperPlane 的编码 RunnerClaude、Codex、OpenCode/OpenRouter在正式构建之前可以进入一种只读的任务精炼模式。该模式下 Agent 不写代码、不改仓库只负责把用户提交的草稿任务打磨清楚。这一模式的核心提示词文件是 analysis_user_prompt.md与其配套的还有一个固定协议文件 analysis_protocol.md负责定义工具与接线两者共同构成分析会话的系统提示词。从 planning_session_assets.go 的源码可以确认这两个 Markdown 文件连同 MCP 服务脚本、mcp.json、续接脚本一起通过//go:embed编译进二进制并由PlanningSessionUserPromptMarkdown()、PlanningSessionProtocolMarkdown()等函数分发。注释中明确说明用户提示词analysis_user_prompt.md负责语气、Clarity 规则与计划形态属于判断层协议analysis_protocol.md负责工具与接线属于机制层。两者冲突时用户提示词胜出见 analysis_protocol.md。分析会话的判定依据是环境变量SUPERPLANE_PLANNING_SESSION_KINDwork_order_analysis见 claude/run.js并且要求会话具备规划令牌HasPlanningSessionToken见 planning_session_token.go。二、五步分析流程总览analysis_user_prompt.md规定每一轮对话都必须严格按顺序执行五个步骤Research研究读懂任务与被改动的代码让计划言之有物。Decide or ask决定或提问小事自己拍板只有用户才能回答的问题才问。Score ClarityClarity 评分任务被定义得有多清楚。Score ConfidenceConfidence 评分编码 Agent 一次运行完成的概率有多大。Write the plan撰写计划当 Clarity 允许时输出规格说明。其中 Clarity 与 Confidence 是相互独立的两个维度——任务清晰不代表 Agent 一定能完成例如涉及不可逆操作或安全敏感代码的清晰任务Confidence 依然很低。两者每轮都必须发布即便 Clarity 很低时 Confidence 也要照常发布Publish it every turn, even when Clarity is low。三、第一步Research先让计划指向真实行为写作任何规格之前Agent 必须先回答四个问题这段行为在代码中由谁负责、今天实际发生了什么两到三种可行的实现方案以及一个称职工程师会选哪一种仓库里是否已有类似的改动可以直接复制哪些测试或命令能证明工作已经完成。研究完成后在聊天中只报告一条发现Say one finding in chat. Do not list findings.用 24 个短句像同事一样交流。文档给出的范例是I found the role dropdown on the members page. Long names wrap or clip. Tell me if the closed control or the open list is the problem.——先陈述自己定位到的事实再抛出需要用户裁决的具体问题。四、第二步Decide or ask提问是稀缺资源该提示词刻意限制提问频率A simple task can reach 5 with no survey. Do not invent a survey to fill a quota.简单任务不需要任何提问也能拿到 Clarity 5不要为了凑提问数而发明问卷。允许提问的四种情况包含还是跳过某个行为两种真实实现各有不同取舍完成的定义是什么——当它会改变工作量时当放弃一部分、拆分任务或走更简单的路径能提升 Confidence 时。**Agent 应自行决定的默认项**命名、文案细节、复用哪个辅助函数、显而易见的文件位置、以及一个称职实现者不问也会选的默认方案。这些默认决定要写进规格说明并且算作已决定因此可以让 Clarity 上升。问卷问题的写作规范也很具体每个问题一句大白话每个选项不超过 12 个词用日常词汇推荐选项放在第一位Put the option you recommend first例如Title, description, and assignees。五、第三步Clarity 评分衡量任务被定义得多清楚Clarity 衡量的是任务的定义程度结果、范围、以及完成的含义是否都已确定而不是 Agent 能不能干——那是 Confidence 的事。分值判定标准5结果、范围、完成都已决定计划指向真实行为没有任何开放选择4还有一个小选择未定但无论选哪个计划形态不变3结果清晰但范围或完成的定义不清可以写第一版计划2结果清晰但计划要靠猜才知道要建什么1任务根本没说要改什么Clarity 为 1 或 2 时禁止写规格说明要明说没有足够的 Clarity 来写计划并邀请用户细化。Clarity 为 3 或 4 时写计划但必须声明这是第一版并邀请用户继续细化Clarity 为 5 时直接写正式规格说明。Clarity 摘要也有硬性规则用you对用户说话不超过两个短句不写分号长链不在摘要里讨论 Agent 适配性那是 Confidence 摘要的事不重复数字本身——因为 UI 会在数字旁显示摘要摘要的作用是解释数字而非复述它。Clarity 为 5 时摘要为The plan is ready. Review it and start if you are happy.低于 5 时必须先说清楚为什么不是 5缺少哪个事实或决策再说用户现在必须补充/决定/回答什么。六、第四步Confidence 评分衡量一次运行能否完成Confidence 衡量的是**一旦计划清晰一个具备完整仓库、计划与测试的编码 Agent 是否能在一次运行内、无需中途纠偏地完成该任务。**清晰的计划中Agent 仍需处理它擅长的部分——It reads code well, follows an existing pattern well, and runs commands to check its work它失败于必须靠猜的品味、产品意图、未写下来的上下文以及无法证明完成的情况。评分依据来自仓库调研而非任务文字五个考察维度Size规模是否适合一次运行数的是 Agent 必须触碰的接缝数而不是描述的行数Proof证明是否有 Agent 可运行的测试或命令来证明完成Pattern模式仓库里是否已有类似的改动可复制Judgment判断未写下来的品味、产品决策或上下文Blast radius爆炸半径迁移、鉴权、计费、生产数据、难以回滚的工作。评分锚点Anchors5一次运行能完成、已有可复制模式、完成可由测试或命令证明、易回滚4一次运行能完成、有模式或改动受限、完成的一部分需要人工看一眼3一次运行能完成但预计要一轮纠偏——改动跨越需要不同上下文的区域或完成无法用命令展示或有一个判断点未定2不适合一次运行或依赖未写下的上下文或检查结果比做事还贵——应提议拆分或收窄范围1完全不适合一次运行——不可逆操作、安全敏感代码或无法展示完成——应提议拆分或加入人工步骤。校准规则同样具体起点是有模式的有界改动 4当完成可由测试/命令证明且改动易回滚时升到 5只有当你在代码里找到了具体理由才降分且要在摘要中点名这个理由。计划已代为决定的判断点不降低 Confidence只有开放的判断才降。缺少测试最多只降一级前提是改动小且可手工验证。文档还专门强调Do not soften a 1 or 2 to spare the user; a wrong 4 costs them a failed run.——不要为了照顾用户情绪把 1、2 分说成 4 分一个错误的 4 分意味着一次注定失败的运行。通过细化提升 ConfidenceConfidence 不是固定的看到提升路径就要主动提出。五种有效手段砍掉一个增加风险但不增加价值的部件拆成两三个各自适配一次运行的任务并点名拆分方式先写一个失败测试让完成变得可证明把开放的判断点变成计划中的决定把高风险步骤放到人工审核之后其余留给 Agent。任务拆分Split当拆分能提升 Confidence 时用问卷提出选项要能让用户看清形态——第一个选项是你推荐的拆分另一个选项保持任务整体。拆分需控制在两三个任务每个部分都必须适配一次运行且能独立成立。示例Split: table and worker first, screens second | Keep it as one task。拆分流程有严格约束只有用户确认后才能创建新任务已确认的拆分通过create_taskMCP 工具落地一次调用创建一个新任务标题短促、描述自包含、不引用本次对话。拆分后本任务保留第一个部分计划随之收窄并重新评分。拆分的一部分当任务描述声明某个依赖由别的任务负责或会话上下文指出了拆分中的其他部分时该边界即已决定——那不是缺失的工作不是开放问题不要问如何处理、不要为它写 stub、不要因为它尚未入库而降 Confidence只需按描述给出的接口来计划并在聊天中说一次你依赖哪个部分然后只评本任务自己负责的工作。Confidence 摘要同样用you、两个短句以内。4 或 5 分时用一句话说明为什么 Agent 能一次运行完成3 分及以下时点名唯一拉低分数的因素然后说出能提升分数的动作拆分、收窄范围、先写测试或人工步骤。Clarity 为 1 或 2 时要声明 Confidence 是临时的直到任务清晰。七、第五步写计划规格说明的结构规范只有当 Clarity ≥ 3 时才写规格说明。短摘要给操作者看构建规格给执行 Agent 看两者不得互相重复。规格说明以一行# 8 个词以内的结果开头随后跟一段无标题的目标陈述禁止 I think禁止给这段加标题。然后是固定顺序的规格摘要区## Problem问题现状痛点## Proposed outcome拟议结果改动后发生什么## Constraints约束不得做什么。只有在某个 Mermaid 图能显著帮助理解 UI 流程或架构时才在 Constraints 之后追加## Diagram。规格摘要之后是构建规格固定顺序为## Scope范围说明什么在内、什么在外## Approach方案按顺序告诉实现者做什么并点名现有文件与接缝## Acceptance验收包含测试与已知命令## Risks风险仅当 Clarity5 且 Confidence≥4 时可跳过。Clarity 3/4 时 Risks 必须说明不确定性及原因Confidence 3 及以下时 Risks 必须点名实现者会在哪里需要人工决策或审核以及你提议的拆分或收窄范围。全程使用美式英语、不解释仓库或产品、规格内不用 I/youDo not write I or you in the specification。八、工程接线只读工具集与 MCP 契约分析会话的机制层由 analysis_protocol.md 定义。它规定 Agent只能使用协议中的分析工具、只能探索仓库、禁止编辑或写入仓库文件唯一的例外是经用户确认拆分后通过create_task创建新草稿任务。从 claude/run.js 的源码可以看到具体的工具接线规划会话的工具白名单是PLANNING_READONLY_TOOLS Read,Bash——Edit/Write 被显式排除注释说明这是为了防止 Agent 在起草任务时改动仓库分析会话的固定工具基座ANALYSIS_BASE_ALLOWED_TOOLS包含四个 MCP 工具propose_spec、survey、create_task、inspect_attachmentpropose_clarity与propose_confidence按环境开关条件性插入见 claude/run.js。这些 MCP 工具的具体语义定义在 planning_session_mcp.js 中propose_spec用于发布完整规格说明propose_clarity每轮发布 15 分及短摘要可在不重写规格时单独调用propose_confidence同理survey以 JSON 结构{questions:[{prompt:...,options:[...,...]}]}向用户呈现 24 个选项且禁止用 XML 标签、禁止把问题编码成 JSON 字符串create_task只能在用户确认拆分后调用。协议还规定调用survey时聊天必须以Answer the questions in this session.开头且不得再把问题写进聊天如果 survey 工具不可用就声明 SuperPlane 无法打开问卷然后停止。规格说明发布走propose_spec调用写文件本身不算发布Writing a file does not publish the specification or the score任务文件以sp-file://引用持久化禁止持久化带签名的 URL。九、运行时开关按需裁剪协议分析协议文本是动态生成的核心实现在 analysis_protocol.js 中。两个环境开关控制协议裁剪SUPERPLANE_PLANNING_CLARITY默认开启envFlagDefaultTrue即false/0/no/off之外的任何值都视为开启SUPERPLANE_PLANNING_CONFIDENCE默认开启。四种组合对应四种协议文本双开时保留完整协议只开 Clarity 时删掉所有 Confidence 相关的发布与调用指令只开 Confidence 时反之双关时两个评分都不发布。裁剪通过精确的字符串replace实现见 analysis_protocol.js。同一脚本还提供withoutEmbeddedAnalysisProtocol从已拼入的提示词中剥离协议文本避免重复嵌入与withAnalysisContinuation首轮对话时把analysis_continuation.md前置拼入提示词见 analysis_protocol.js。十、续接与会话生命周期分析会话不是一轮就结束的SuperPlane 在 Agent 停下后等待用户回答用户每回复一条消息会话就续接一轮。续接文案由数据库侧生成PlanningSessionContinuationFile读取规划会话仅在IsAnalysisSession()为真时产出analysis_continuation.md任务文件见 planning_session_assets.gofollow_up_loop.js 负责在等待循环中把该文件交给下一轮。IsAnalysisSession()由PlanningSessionKind判定测试用例明确验证了分析会话与任务创建会话的区分见 planning_session_token_test.go。协议对续接轮也有行为约束如果首轮提示词里已带当前规格说明或历史消息这是续接而非新会话——不要当作新会话打招呼直接遵循任务提示词并应用最新消息。十一、测试如何验证这套行为analysis_user_prompt.md定义的行为在仓库中有配套测试印证。以 Claude Runner 为例claude/run_test.go 验证了分析模式下工具列表包含propose_spec、propose_clarity、propose_confidence仅开 Clarity 时包含propose_clarity且不包含propose_confidence仅开 Confidence 时反之非分析模式下这些 MCP 工具不出现在白名单中。OpenRouter Runner 的测试则验证了superplane_propose_spec工具调用的名称与顺序见 openrouter/run_test.go。这些测试直接印证了第九节的开关裁剪逻辑与第八节的工具白名单。十二、自定义与分析会话的定位analysis_user_prompt.md是默认的 Refine Task 提示词其注释明确说明Factories can edit that node prompt——即工厂Factory工作流中的该节点提示词可被编辑替换见 planning_session_assets.go。而analysis_protocol.md是硬编码的固定协议Runner 会将其追加进系统提示词画布提示词不得覆盖它。需要强调的是这套分析会话是一次性工程one-shot engineering流水线的前置环节它的产出不是代码而是让编码 Agent 在正式运行中不必猜、不必回头问的构建规格。Clarity 保证做什么没有歧义Confidence 保证一次能不能做完两者共同把一次运行的失败率压到最低——这正是analysis_user_prompt.md全文反复强调的设计目标your job is to get the task to a state where an agent will succeed, not to grade it and walk away你的职责是把任务打磨到 Agent 能成功完成的状态而不是评完分就撒手不管。赞分享【免费下载链接】superplaneOpen source factory for one-shot engineering项目地址https://gitcode.com/gh_mirrors/su/superplane点击查看免费下载相关推荐Superpowers 深度解析 task-reviewer-prompt.md:单任务、双裁决的 SDD 评审模板设计Superpowers 深度解析 task reviewer prompt.md:单任务、双裁决的 SDD 评审模板设计 本文以 task reviewer pAI 技能AI 插件开发工具LX Music 使用指南免费聚合五大音源一次装好随处听歌LX Music 使用指南免费聚合五大音源一次装好随处听歌 想找一首歌手边这个 App 里没有了另一个 App 又开了会员门槛。LX Music 桌面版桌面应用音视频前端OpenHuman 会话 transcript 收敛设计解析agent 会话存档与 TinyAgents ChatHistory 的边界划分OpenHuman 会话 transcript 收敛设计解析agent 会话存档与 TinyAgents ChatHistory 的边界划分 导读 src/o人工智能AI 应用本地部署AI Agent交互助手深度研究上一篇5分钟学会Unreal引擎存档编辑uesave-rs完整指南下一篇PianoPlayer告别指法困惑AI为你量身定制钢琴演奏方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SuperPlane Refine Task 分析会话：Clarity/Confidence 双评分驱动的任务精炼 Agent 设计
【免费下载链接】superplaneOpen source factory for one-shot engineering项目地址https://gitcode.com/gh_mirrors/su/superplane点击查看免费下载本文讲解 SuperPlane 中Refine Task任务精炼分析会话的完整设计。它定义了编码 Agent 在执行任务前如何通过研究仓库、提问、评分与撰写规格说明把一段粗糙的草稿任务打磨成一次运行即可交付的构建任务。读完本文你将掌握五步分析流程、Clarity 与 Confidence 双维评分体系的判定标准、规格说明的结构规范以及这套逻辑在仓库中的工程接线方式。一、什么是 Refine Task 分析会话SuperPlane 的编码 RunnerClaude、Codex、OpenCode/OpenRouter在正式构建之前可以进入一种只读的任务精炼模式。该模式下 Agent 不写代码、不改仓库只负责把用户提交的草稿任务打磨清楚。这一模式的核心提示词文件是 analysis_user_prompt.md与其配套的还有一个固定协议文件 analysis_protocol.md负责定义工具与接线两者共同构成分析会话的系统提示词。从 planning_session_assets.go 的源码可以确认这两个 Markdown 文件连同 MCP 服务脚本、mcp.json、续接脚本一起通过//go:embed编译进二进制并由PlanningSessionUserPromptMarkdown()、PlanningSessionProtocolMarkdown()等函数分发。注释中明确说明用户提示词analysis_user_prompt.md负责语气、Clarity 规则与计划形态属于判断层协议analysis_protocol.md负责工具与接线属于机制层。两者冲突时用户提示词胜出见 analysis_protocol.md。分析会话的判定依据是环境变量SUPERPLANE_PLANNING_SESSION_KINDwork_order_analysis见 claude/run.js并且要求会话具备规划令牌HasPlanningSessionToken见 planning_session_token.go。二、五步分析流程总览analysis_user_prompt.md规定每一轮对话都必须严格按顺序执行五个步骤Research研究读懂任务与被改动的代码让计划言之有物。Decide or ask决定或提问小事自己拍板只有用户才能回答的问题才问。Score ClarityClarity 评分任务被定义得有多清楚。Score ConfidenceConfidence 评分编码 Agent 一次运行完成的概率有多大。Write the plan撰写计划当 Clarity 允许时输出规格说明。其中 Clarity 与 Confidence 是相互独立的两个维度——任务清晰不代表 Agent 一定能完成例如涉及不可逆操作或安全敏感代码的清晰任务Confidence 依然很低。两者每轮都必须发布即便 Clarity 很低时 Confidence 也要照常发布Publish it every turn, even when Clarity is low。三、第一步Research先让计划指向真实行为写作任何规格之前Agent 必须先回答四个问题这段行为在代码中由谁负责、今天实际发生了什么两到三种可行的实现方案以及一个称职工程师会选哪一种仓库里是否已有类似的改动可以直接复制哪些测试或命令能证明工作已经完成。研究完成后在聊天中只报告一条发现Say one finding in chat. Do not list findings.用 24 个短句像同事一样交流。文档给出的范例是I found the role dropdown on the members page. Long names wrap or clip. Tell me if the closed control or the open list is the problem.——先陈述自己定位到的事实再抛出需要用户裁决的具体问题。四、第二步Decide or ask提问是稀缺资源该提示词刻意限制提问频率A simple task can reach 5 with no survey. Do not invent a survey to fill a quota.简单任务不需要任何提问也能拿到 Clarity 5不要为了凑提问数而发明问卷。允许提问的四种情况包含还是跳过某个行为两种真实实现各有不同取舍完成的定义是什么——当它会改变工作量时当放弃一部分、拆分任务或走更简单的路径能提升 Confidence 时。**Agent 应自行决定的默认项**命名、文案细节、复用哪个辅助函数、显而易见的文件位置、以及一个称职实现者不问也会选的默认方案。这些默认决定要写进规格说明并且算作已决定因此可以让 Clarity 上升。问卷问题的写作规范也很具体每个问题一句大白话每个选项不超过 12 个词用日常词汇推荐选项放在第一位Put the option you recommend first例如Title, description, and assignees。五、第三步Clarity 评分衡量任务被定义得多清楚Clarity 衡量的是任务的定义程度结果、范围、以及完成的含义是否都已确定而不是 Agent 能不能干——那是 Confidence 的事。分值判定标准5结果、范围、完成都已决定计划指向真实行为没有任何开放选择4还有一个小选择未定但无论选哪个计划形态不变3结果清晰但范围或完成的定义不清可以写第一版计划2结果清晰但计划要靠猜才知道要建什么1任务根本没说要改什么Clarity 为 1 或 2 时禁止写规格说明要明说没有足够的 Clarity 来写计划并邀请用户细化。Clarity 为 3 或 4 时写计划但必须声明这是第一版并邀请用户继续细化Clarity 为 5 时直接写正式规格说明。Clarity 摘要也有硬性规则用you对用户说话不超过两个短句不写分号长链不在摘要里讨论 Agent 适配性那是 Confidence 摘要的事不重复数字本身——因为 UI 会在数字旁显示摘要摘要的作用是解释数字而非复述它。Clarity 为 5 时摘要为The plan is ready. Review it and start if you are happy.低于 5 时必须先说清楚为什么不是 5缺少哪个事实或决策再说用户现在必须补充/决定/回答什么。六、第四步Confidence 评分衡量一次运行能否完成Confidence 衡量的是**一旦计划清晰一个具备完整仓库、计划与测试的编码 Agent 是否能在一次运行内、无需中途纠偏地完成该任务。**清晰的计划中Agent 仍需处理它擅长的部分——It reads code well, follows an existing pattern well, and runs commands to check its work它失败于必须靠猜的品味、产品意图、未写下来的上下文以及无法证明完成的情况。评分依据来自仓库调研而非任务文字五个考察维度Size规模是否适合一次运行数的是 Agent 必须触碰的接缝数而不是描述的行数Proof证明是否有 Agent 可运行的测试或命令来证明完成Pattern模式仓库里是否已有类似的改动可复制Judgment判断未写下来的品味、产品决策或上下文Blast radius爆炸半径迁移、鉴权、计费、生产数据、难以回滚的工作。评分锚点Anchors5一次运行能完成、已有可复制模式、完成可由测试或命令证明、易回滚4一次运行能完成、有模式或改动受限、完成的一部分需要人工看一眼3一次运行能完成但预计要一轮纠偏——改动跨越需要不同上下文的区域或完成无法用命令展示或有一个判断点未定2不适合一次运行或依赖未写下的上下文或检查结果比做事还贵——应提议拆分或收窄范围1完全不适合一次运行——不可逆操作、安全敏感代码或无法展示完成——应提议拆分或加入人工步骤。校准规则同样具体起点是有模式的有界改动 4当完成可由测试/命令证明且改动易回滚时升到 5只有当你在代码里找到了具体理由才降分且要在摘要中点名这个理由。计划已代为决定的判断点不降低 Confidence只有开放的判断才降。缺少测试最多只降一级前提是改动小且可手工验证。文档还专门强调Do not soften a 1 or 2 to spare the user; a wrong 4 costs them a failed run.——不要为了照顾用户情绪把 1、2 分说成 4 分一个错误的 4 分意味着一次注定失败的运行。通过细化提升 ConfidenceConfidence 不是固定的看到提升路径就要主动提出。五种有效手段砍掉一个增加风险但不增加价值的部件拆成两三个各自适配一次运行的任务并点名拆分方式先写一个失败测试让完成变得可证明把开放的判断点变成计划中的决定把高风险步骤放到人工审核之后其余留给 Agent。任务拆分Split当拆分能提升 Confidence 时用问卷提出选项要能让用户看清形态——第一个选项是你推荐的拆分另一个选项保持任务整体。拆分需控制在两三个任务每个部分都必须适配一次运行且能独立成立。示例Split: table and worker first, screens second | Keep it as one task。拆分流程有严格约束只有用户确认后才能创建新任务已确认的拆分通过create_taskMCP 工具落地一次调用创建一个新任务标题短促、描述自包含、不引用本次对话。拆分后本任务保留第一个部分计划随之收窄并重新评分。拆分的一部分当任务描述声明某个依赖由别的任务负责或会话上下文指出了拆分中的其他部分时该边界即已决定——那不是缺失的工作不是开放问题不要问如何处理、不要为它写 stub、不要因为它尚未入库而降 Confidence只需按描述给出的接口来计划并在聊天中说一次你依赖哪个部分然后只评本任务自己负责的工作。Confidence 摘要同样用you、两个短句以内。4 或 5 分时用一句话说明为什么 Agent 能一次运行完成3 分及以下时点名唯一拉低分数的因素然后说出能提升分数的动作拆分、收窄范围、先写测试或人工步骤。Clarity 为 1 或 2 时要声明 Confidence 是临时的直到任务清晰。七、第五步写计划规格说明的结构规范只有当 Clarity ≥ 3 时才写规格说明。短摘要给操作者看构建规格给执行 Agent 看两者不得互相重复。规格说明以一行# 8 个词以内的结果开头随后跟一段无标题的目标陈述禁止 I think禁止给这段加标题。然后是固定顺序的规格摘要区## Problem问题现状痛点## Proposed outcome拟议结果改动后发生什么## Constraints约束不得做什么。只有在某个 Mermaid 图能显著帮助理解 UI 流程或架构时才在 Constraints 之后追加## Diagram。规格摘要之后是构建规格固定顺序为## Scope范围说明什么在内、什么在外## Approach方案按顺序告诉实现者做什么并点名现有文件与接缝## Acceptance验收包含测试与已知命令## Risks风险仅当 Clarity5 且 Confidence≥4 时可跳过。Clarity 3/4 时 Risks 必须说明不确定性及原因Confidence 3 及以下时 Risks 必须点名实现者会在哪里需要人工决策或审核以及你提议的拆分或收窄范围。全程使用美式英语、不解释仓库或产品、规格内不用 I/youDo not write I or you in the specification。八、工程接线只读工具集与 MCP 契约分析会话的机制层由 analysis_protocol.md 定义。它规定 Agent只能使用协议中的分析工具、只能探索仓库、禁止编辑或写入仓库文件唯一的例外是经用户确认拆分后通过create_task创建新草稿任务。从 claude/run.js 的源码可以看到具体的工具接线规划会话的工具白名单是PLANNING_READONLY_TOOLS Read,Bash——Edit/Write 被显式排除注释说明这是为了防止 Agent 在起草任务时改动仓库分析会话的固定工具基座ANALYSIS_BASE_ALLOWED_TOOLS包含四个 MCP 工具propose_spec、survey、create_task、inspect_attachmentpropose_clarity与propose_confidence按环境开关条件性插入见 claude/run.js。这些 MCP 工具的具体语义定义在 planning_session_mcp.js 中propose_spec用于发布完整规格说明propose_clarity每轮发布 15 分及短摘要可在不重写规格时单独调用propose_confidence同理survey以 JSON 结构{questions:[{prompt:...,options:[...,...]}]}向用户呈现 24 个选项且禁止用 XML 标签、禁止把问题编码成 JSON 字符串create_task只能在用户确认拆分后调用。协议还规定调用survey时聊天必须以Answer the questions in this session.开头且不得再把问题写进聊天如果 survey 工具不可用就声明 SuperPlane 无法打开问卷然后停止。规格说明发布走propose_spec调用写文件本身不算发布Writing a file does not publish the specification or the score任务文件以sp-file://引用持久化禁止持久化带签名的 URL。九、运行时开关按需裁剪协议分析协议文本是动态生成的核心实现在 analysis_protocol.js 中。两个环境开关控制协议裁剪SUPERPLANE_PLANNING_CLARITY默认开启envFlagDefaultTrue即false/0/no/off之外的任何值都视为开启SUPERPLANE_PLANNING_CONFIDENCE默认开启。四种组合对应四种协议文本双开时保留完整协议只开 Clarity 时删掉所有 Confidence 相关的发布与调用指令只开 Confidence 时反之双关时两个评分都不发布。裁剪通过精确的字符串replace实现见 analysis_protocol.js。同一脚本还提供withoutEmbeddedAnalysisProtocol从已拼入的提示词中剥离协议文本避免重复嵌入与withAnalysisContinuation首轮对话时把analysis_continuation.md前置拼入提示词见 analysis_protocol.js。十、续接与会话生命周期分析会话不是一轮就结束的SuperPlane 在 Agent 停下后等待用户回答用户每回复一条消息会话就续接一轮。续接文案由数据库侧生成PlanningSessionContinuationFile读取规划会话仅在IsAnalysisSession()为真时产出analysis_continuation.md任务文件见 planning_session_assets.gofollow_up_loop.js 负责在等待循环中把该文件交给下一轮。IsAnalysisSession()由PlanningSessionKind判定测试用例明确验证了分析会话与任务创建会话的区分见 planning_session_token_test.go。协议对续接轮也有行为约束如果首轮提示词里已带当前规格说明或历史消息这是续接而非新会话——不要当作新会话打招呼直接遵循任务提示词并应用最新消息。十一、测试如何验证这套行为analysis_user_prompt.md定义的行为在仓库中有配套测试印证。以 Claude Runner 为例claude/run_test.go 验证了分析模式下工具列表包含propose_spec、propose_clarity、propose_confidence仅开 Clarity 时包含propose_clarity且不包含propose_confidence仅开 Confidence 时反之非分析模式下这些 MCP 工具不出现在白名单中。OpenRouter Runner 的测试则验证了superplane_propose_spec工具调用的名称与顺序见 openrouter/run_test.go。这些测试直接印证了第九节的开关裁剪逻辑与第八节的工具白名单。十二、自定义与分析会话的定位analysis_user_prompt.md是默认的 Refine Task 提示词其注释明确说明Factories can edit that node prompt——即工厂Factory工作流中的该节点提示词可被编辑替换见 planning_session_assets.go。而analysis_protocol.md是硬编码的固定协议Runner 会将其追加进系统提示词画布提示词不得覆盖它。需要强调的是这套分析会话是一次性工程one-shot engineering流水线的前置环节它的产出不是代码而是让编码 Agent 在正式运行中不必猜、不必回头问的构建规格。Clarity 保证做什么没有歧义Confidence 保证一次能不能做完两者共同把一次运行的失败率压到最低——这正是analysis_user_prompt.md全文反复强调的设计目标your job is to get the task to a state where an agent will succeed, not to grade it and walk away你的职责是把任务打磨到 Agent 能成功完成的状态而不是评完分就撒手不管。赞分享【免费下载链接】superplaneOpen source factory for one-shot engineering项目地址https://gitcode.com/gh_mirrors/su/superplane点击查看免费下载相关推荐Superpowers 深度解析 task-reviewer-prompt.md:单任务、双裁决的 SDD 评审模板设计Superpowers 深度解析 task reviewer prompt.md:单任务、双裁决的 SDD 评审模板设计 本文以 task reviewer pAI 技能AI 插件开发工具LX Music 使用指南免费聚合五大音源一次装好随处听歌LX Music 使用指南免费聚合五大音源一次装好随处听歌 想找一首歌手边这个 App 里没有了另一个 App 又开了会员门槛。LX Music 桌面版桌面应用音视频前端OpenHuman 会话 transcript 收敛设计解析agent 会话存档与 TinyAgents ChatHistory 的边界划分OpenHuman 会话 transcript 收敛设计解析agent 会话存档与 TinyAgents ChatHistory 的边界划分 导读 src/o人工智能AI 应用本地部署AI Agent交互助手深度研究上一篇5分钟学会Unreal引擎存档编辑uesave-rs完整指南下一篇PianoPlayer告别指法困惑AI为你量身定制钢琴演奏方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考