mcpField
A
architect

architect

github.com/jsmastery-pro开发1.6k6.9k 次安装12 周前更新
代码仓库

关于 architect

architect 是用于开展结构化设计梳理并在项目中编写或更新构建规范的 Agent Skill。它涵盖功能、架构、增强和跨领域决策,并由主线程负责撰写规范。

主要功能

  1. 01支持四种设计模式
  2. 02创建和更新构建规范
  3. 03管理规范状态与归属
  4. 04使用只读子 Agent 开展调研
  5. 05规定产物结构和存放位置

适用场景

  1. 01实现前设计新功能
  2. 02比较基础架构方案
  3. 03随项目演进更新决策
  4. 04统一整个代码库中的模式

安装

复制下面的命令,在终端中运行。

$npx skills add https://github.com/jsmastery-pro/skills --skill architect

安装后在 Claude Code 中输入/architect确认已加载。

包含的文件

除 SKILL.md 外,安装时一起下载的参考资料和脚本。

agent-prompt.md
spec-template.md
agent-modes/
architecture.md
cross-cutting.md
enhancement.md
feature.md
agents/
openai.yaml
internal/
after-subagent.md
design-conversation.md
tool-discovery.md

详细介绍

输出风格(使用朴素的词语,不用短横线或连字符)

请用简单直白的语言撰写此技能生成的所有内容,包括文件和消息。用 you 称呼读者,像同事一样热情、直接地交流,并把每个步骤都写成建议,让读者可以选择执行或跳过,绝不使用命令式语气。保留有实际含义的技术术语,并用朴素的语言解释每个术语。绝不使用短横线或连字符作为标点:不使用破折号、连接号,也不使用带连字符的复合词。写作时使用 read only,不要写 read-only。请用简单的词语表达,或改写句子。其他技能会匹配的代码、文件路径、命令标志和值要保留其中的连字符。使用短句、逗号或括号。清晰胜过巧妙。

此技能的作用

执行结构化探索,权衡选项,并在 docs/specs/ 中编写或更新构建规范。主线程负责写入,只会将阅读代码库或获取网页内容的工作交给成本较低的子 Agent(见 子 Agent)。包含四种模式:

模式适用情况设计方式
FEATURE从头设计新功能,无论是否已有代码从第一原则出发进行设计,采用最佳实践,尽量少读代码
ARCHITECTURE为新项目选择技术栈或基础架构全面评估技术栈,参考行业模式,不需要阅读代码
ENHANCEMENT改进、替换或扩展已有内容阅读现有代码和规范,有针对性地比较选项
CROSS-CUTTING在整个代码库中统一某种模式(错误处理、日志记录、身份验证、命名)抽查当前情况,准确定义标准,并建议如何落实
  • 创建:做出新决策 → 创建状态为 Proposed 的新规范
  • 更新:调整现有决策 → 直接编辑现有规范
  • 取代:替换过去的决策 → 创建新规范,并更新旧规范的状态行
  • 确认:审议 /develop 在工程师决定先构建再决策时记录的 Assumed 规范 → 见下文的 确认一项假设决策

规范的状态有两种处理方式,取决于是否有可构建的范围功能关联该规范(即 docs/scope/ 中有一行,其 spec 单元格指向该规范):

  • 关联功能的规范(常见于 FEATURE/ENHANCEMENT,或有范围行关联的 ARCHITECTURE 基础规范):状态与功能生命周期同步。/architect 创建状态为 Proposed 的规范,并负责维护其内容,但绝不推进其状态;功能进入进行中后,/develop 将其状态推进为 In Progress,功能构建并验证完成后(范围状态为 done),再推进为 Accepted。工程师确认只代表确认内容;Accepted 表示已交付。
  • 独立决策规范(基础架构或技术栈决策,或没有范围行关联的跨领域标准):状态表示决策状态。规范写好后为 Proposed,工程师确认后为 Accepted(此时决策正式生效)。/develop 不会推进其状态。

记录已交付工作的规范(“已构建”路径,或状态为 existing 的已关联功能)一开始就设为 Accepted。

Assumed 状态。 如果工程师选择先构建,而尚未审议某项关键决策,/develop 可以创建状态为 Assumed 的规范。该规范记录构建时采用的假设,而非经过审议的决策。功能仍可标记为 done;Assumed 规范会继续标记为待确认状态,但不会阻止功能完成。只有 /architect 可以通过以下确认流程清除 Assumed 状态。/architect 绝不会创建 Assumed 规范,只会审议已有的此类规范。

不编写代码。绝不更新 AGENTS.md/CLAUDE.md(这由 /sync 负责)。

子 Agent(主线程负责编写;子 Agent 只读、抓取或交叉检查)

主线程负责运行对话并编写规范;它绝不会把编写工作或任何修复交给子 Agent。它生成的每个子 Agent 都是只读的,也不会继承会话模型:

  • 读取代码库(成本最低的模型,Claude Code haiku):当代码库较大(ENHANCEMENT/CROSS-CUTTING)时,只读扫描现有代码。Claude Code:scout 类型。返回精简的概览,绝不倾倒文件内容。
  • 从网络抓取(成本最低的模型,Claude Code haiku):在设计对话(Stage c)期间,当决策需要最新信息时,检查当前工具生态并发现 Agent Skill / MCP。Claude Code:researcher 类型。返回精简摘要,绝不返回原始网页。
  • 交叉检查已起草的规范(主要工作是检查决策是否完整:找出某项操作必须产出的值,但规范未注明其来源;以及构建者原本需要自行编造的决策):只读检查已完成的规范并给出批评意见,不写入任何内容。/architect 总会询问是否运行交叉检查(绝不代替工程师运行或跳过),在 GA/Beta 阶段(这些阶段最容易出现此类问题)强烈建议运行,在 Alpha 阶段提供此选项,在 Prototype 阶段建议跳过;发现的任何缺口都会连同建议修复方案一起提交给工程师,由工程师决定,不会自动解决。参见规范编写完成后。

仅在决策需要网络信息时抓取一次(即 Stage (c) 的生态和工具发现检查)。抓取后返回的链接会放入规范的 References 中,供人工查阅;AI 不会再次抓取这些链接(不会在交叉检查、/develop 或 /audit 中抓取)。

提问与行动

编写规范之前(以及生成任何只读/抓取辅助 Agent 之前)提出有针对性的问题;把预算花在实质内容上。对每个问题分类:

  • INFER:提示或代码库已经揭示的内容(功能还是架构、技术栈、涉及的 UI、已选定的提供方)。自行推断,不要提问。
  • ASK:只有工程师本人知道的内容(需求、偏好、业务规则、合规范围)。
  • RECOMMEND:专业知识可以确定的内容(适合的提供方/库/模式)。说明推荐选择、简短理由以及备选方案;工程师可以覆盖建议。绝不提供不带倾向的选项菜单,也绝不默默替工程师做决定。

绝不要把完整数据模型、完整技术栈或现成的验收标准集合打包成一个接受或修改面板,也绝不要默默决定工具、提供方或设置选项。

建议应与正在使用的技术栈保持一致(使用 BaaS 时,优先采用其身份验证/存储方案,而不是引入新的外部工具;复用胜过扩张)。无论 Web 还是移动端:都要推断平台,绝不默认是 Web。

这是意图,而非流程。如何开展提问,详见 internal/design-conversation.md;下文的 Execution 要求你在提出任何设计问题之前完整阅读该文件。

工件归属

仅由此技能创建或更新的 docs/specs/ 中的规格文件,以及由此产生的任何支撑证据(清单、审计),都应放在规格文件的 rationale.md 中(目录型规格)或内联写入(单文件规格),绝不能放进范围文件夹(docs/scope/ 归 /scope 所有,不属于规格)。

有两个相互独立的选择:位置(仓库形态)和结构(决策规模):

  • 位置 = 仓库形态。 单仓库 → docs/specs/。单体仓库 → 工作区决策放在 docs/specs/<workspace>/,整个仓库范围的决策放在 docs/specs/_root/(与范围目录对应)。编号按位置分别递增(扫描该目录以确定下一个 NNNN)。将解析后的路径记为 $SPEC_DIR。
  • 结构 = 决策规模,与仓库形态无关。简单决策:一个文件 $SPEC_DIR/NNNN-title.md(所有内容内联,简洁撰写)。伞形决策(相关子决策)、复杂或基础性决策,或需要 verify.md 的决策,使用目录结构:$SPEC_DIR/NNNN-title/,以 index.md 作为顶层文件,旁边放置 rationale.md(伞形决策还包含子规格 NNNN-<child>.md)。切勿重复名称(NNNN-title/NNNN-title.md);目录名中已包含编号,顶层文件应为 index.md。默认使用单文件。

目录型规格始终恰好包含两个核心文件(另可包含可选的 verify.md 和子规格):

  • index.md:/develop 读取的构建规格,包含:## Summary、## Requirements、## Decision、设计/规格部分、## Build plan、## Consequences、## Follow-up,以及一行指向 rationale.md 的 ## Rationale 引用。伞形决策还需在开头提供 ## Structure 清单,列出并链接每个子规格(每项一行:说明其内容及所支持的决策),并涵盖跨子规格约定。
  • rationale.md:/develop 会跳过的决策记录,包含:## Context、## Options considered、## Rationale、## References 部分,以及任何归入其自有子标题的较大规模证据(清单、审计)。不设 research/ 文件夹;所有证据都放在此处。
  • 子规格(仅限伞形决策)为扁平的 NNNN-<child>.md 文件,每份都应足够完整,可独立用于构建,并附有简短的内联理由(不单独设置 rationale.md);只有当子规格变得复杂时,才将其升级为独立目录。跨子规格约定放在伞形决策的 index.md 中。
  • 范围内唯一的狭窄例外: 规格确认后,将对应功能更新为可开始构建的状态(具体修改见 编写规格后 的第 3 步)。切勿把原子任务清单倾倒到范围文件夹中。若没有对应功能,则提议添加一个(参见派生任务步骤)。

工件根目录。 默认将规格放在 docs/ 下。如果检测到 docs/ 是已发布的文档站点(docusaurus.config.*、.vitepress/、mkdocs.yml、Astro Starlight 或 Nextra),则改用 .workflow/(.workflow/specs/)。始终遵循已有的根目录(此处路径均假设使用 docs/)。


可移植性(任意操作系统、任意 Agent)

  • 命令: git 是唯一必需的命令行工具,在所有操作系统上都相同。其他 shell 片段(mkdir -p、date、find、ls、cat、wc)仅供参考,遵循 POSIX,并非需要原样执行的脚本;请使用 Agent 提供的跨平台文件工具(读取、搜索/全局匹配、写入、创建目录),并根据你对今天日期的了解操作。使用写入工具创建 docs/specs/,不要使用 mkdir。
  • 随附文件: agent-prompt.md、agent-modes/*.md 和 spec-template.md 的路径均相对于此技能文件夹。主线程会在写入规格前立即自行读取这些文件(见 编写规格):agent-prompt.md(角色设定、规则和报告格式)、匹配的 agent-modes/<mode>.md,以及 spec-template.md(章节结构)。仅在写入时读取这些文件,不要在预检期间读取,以免它们在整个访谈过程中一直占用上下文。
  • 不支持交互式提问? 使用 Agent 提供的任何功能(选项选择器);仅在没有此功能时,才退而使用纯文本按相同选项逐轮提问。

执行

步骤 0:主题检查(预检之前)

如果未提供设计主题(/architect 未带参数,或描述为空),请停止并先询问,暂勿执行其他操作:

“你想要梳理哪项设计决策?请用一两句话描述你需要设计的功能、系统或选择。”

等待对方回答;在预检前,将其作为设计主题。


预检(主模型)

执行以下步骤(git 命令需原样执行;其他操作均使用 Agent 的文件工具):

  • 新鲜度(团队协作): 静默执行 git fetch,选择基础分支(如果 git rev-parse --verify main 成功,则选 main,否则选 master),通过 git rev-list --count HEAD..origin/<base> 统计落后的提交数。如果 >0,在做决定前提醒“请先拉取”(队友可能添加了规范或更改了此功能)。
  • 确定规范位置(SPEC_DIR)= 映射到 docs/specs/ 的范围工作区:单仓库 → docs/specs/;monorepo 工作区 → docs/specs/<workspace>/;全仓库范围 → docs/specs/_root/。按照范围的定义确定 <workspace>(主题/路径/范围行)。如果目录不存在,则创建。
  • 今天的日期:使用今天的日期(写入规范)。
  • 列出此位置已有的规范:在 $SPEC_DIR 中查找名为 NNNN-*.md 的文件以及任何 index.md,用于编号(按位置分别编号)和检测相关决策。
  • 统计源文件(例如 .ts、.tsx、.js、.py、.go、.rs、.java),排除 node_modules/、.git/、dist/。据此判断需要阅读多少代码,以及是否将阅读工作交给 scout 子 Agent。
  • 阅读项目上下文,即技术栈和社区技能的事实来源:根目录的 AGENTS.md(若不存在,则依次查找 CLAUDE.md,否则标记为 MISSING),以及此功能所属区域的嵌套 <area>/AGENTS.md(如果存在,例如身份验证功能对应的 src/auth/AGENTS.md)。
  • 阅读此功能的构建方法:决定规范中 ## Build plan 的排序和分段的交付策略。优先级:此功能范围行中声明的 Approach 覆盖项;否则使用项目默认值(先看根目录 AGENTS.md,再看 docs/scope/ 中的范围标题)。采用专属构建方法的功能按其自身方法构建;其他功能使用项目默认方法。这四种方法对应实质不同的 ## Build plan 排序,而不是仅更换标签:Tracer Bullet 先搭建贯穿每一层的精简端到端链路,然后逐步扩展;Skateboard 先构建最精简但完整可用的版本,然后逐步扩展;Facade 先使用占位数据搭建 UI 外壳,并推迟迁移(原型路径);Journey 先完整完成一条用户路径中的任务,再处理下一条。如果项目未记录相关方法,可使用项目特定变体。如果两处都未记录,则注明采用的假设,并由 Staff/Principal 判断默认方法(生产工作优先采用端到端的 Tracer Bullet 切片)。排序应清楚体现所记录的方法。
  • 定位关联的范围功能(如果有):快速扫描 docs/scope/ 的文件名和标题(包括各工作区的子目录),查找与此主题匹配的功能;只打开包含该功能的单个范围文件(scope.md,或拆分文件中的匹配 <epic>.md)。如果找到,则阅读该行的意图和任何验收标准初稿(这些内容将作为阶段 (a) 的基础),并记住文件和行,以用于派生任务和关联步骤;这也可确定功能是关联功能还是独立功能。如果没有匹配行,则注明采用独立决策路径,不要现在新建范围条目。
  • (可选) 列出已安装的技能目录,仅用于确认可用性(.claude/skills/、.agents/skills/、skills/)。是否相关应根据 AGENTS.md 和功能本身来判断,而不是按名称匹配。 从规格列表中(路径相对于 $SPEC_DIR):
  • 下一个编号:取现有最大编号 + 1,补零至 4 位;如果没有,则使用 0001(伞形目录也算一个编号)。冲突防护(团队协作):写入前立即再次列出 $SPEC_DIR;如果选定的 NNNN 已存在,则递增至下一个可用编号。绝不覆盖现有规格;写入后,确认没有并发运行使用相同编号。
  • 文件名 / 结构:根据主题生成 kebab-case 短语,最多 5 个词,不含冠词,全部小写。
    • 简单决策 → $SPEC_DIR/NNNN-kebab-title.md。
    • 伞形规格(拆分为 ≥2 个相关子决策)→ 目录 $SPEC_DIR/NNNN-kebab-title/,其中包含 index.md(列出子项的伞形决策)、rationale.md(推理过程 + 任何清单/审计)以及其中的子规格 NNNN-child.md。写入前根据主题的范围确定结构,并在写作时牢记这一结构。
  • 相关规格:分两步读取,随着规格增多,保持这一过程开销较低。首先只读取每个现有规格的标题行(即使有几十个也很省时);然后只读取标题可能与此主题重叠的少数规格的前 20 行(标题、状态、上下文开篇),以确认是否相关。标记匹配项。
  • 伞形规格子项检测:如果主题是现有伞形规格($SPEC_DIR/NNNN-<umbrella>/)的子决策,例如在该规格下推进时发现的决策,则将新规格放入该目录,作为下一个子项(NNNN-child.md),并将其添加到伞形规格的 index.md 列表中,而不是新建顶层规格。/develop 在构建过程中遇到决策时也使用相同路径。告知工程师新规格将放置的位置。
  • 更新/取代检测:如果现有规格与主题明显重叠(领域、系统、决策相同),则在分阶段对话开始前展示决策面板(没有选择器时使用纯文本选项;选择器会自动添加 Other):“我发现有一个现有规格可能与此重叠:[path],[title]。你希望如何处理?”选项:新建决策(创建新规格) · 原地更新现有规格 · 取代它(创建新规格以替代它)。根据重叠程度,将默认选项设为“(推荐)”(几乎相同 → 更新或取代;相邻 → 新建)。更新/取代时:设置 OPERATION,完整读取现有规格,并跳过原地更新的分阶段对话。
    • 发现假定规格:如果重叠规格的 **Status**: 为 Assumed,则这是一次确认,而非上述决策面板。遵循“确认假定决策”(Ratify an assumed decision):进行设计对话,然后补充真实内容并清除 Assumed,或者在假设有误时取代该规格。

社区技能来自项目的 AGENTS.md,绝不使用硬编码的名称表(名称和技术栈会变化)。项目范围的技能/约定位于根目录的 AGENTS.md,特定区域的技能/约定位于嵌套的 <area>/AGENTS.md(由 /audit 和 /sync 维护):

  1. 阅读根目录的 AGENTS.md 以及此功能所在区域的嵌套 AGENTS.md;其中的 ## Agent skills 部分以项目符号列出每个已安装的技能及其位置,并用一行说明其管辖范围,因此你可以直接挑出相关的技能及其路径。
  2. 仅识别与此功能相关的技能。从 ## Agent skills 的项目符号中取出每个相关技能的路径和说明,并在撰写时按需打开它,且仅当它实质性地影响决策时才打开(参见编写规范,第 12 项)。跳过此功能未涉及的技能。
  3. 可用 ≠ 相关。你可以列出已安装的技能目录以查看存在哪些技能,但相关性来自该功能加上 AGENTS.md。如果一个明显相关的技能已安装但尚未在 AGENTS.md 中被引用,仍然使用它,并标记(规范跟进项)它应归入正确的上下文文件:若为项目级则归入根目录,若为区域级则归入嵌套的 <area>/AGENTS.md。
  4. 无论上下文文件显示项目已经使用了什么(一个 BaaS、一个 ORM、一个支付服务商、一个认证库),你的库/服务商推荐都必须以此为基础或优先选择它,而不是一个无关的外部工具。如果一个确实更好的选项尚未安装,将其记为规范跟进项,而不是默不作声地假定它。

工作流技能(切勿当作社区技能):audit、architect、scope、develop、check、test、document、debug、sync,以及随其创建而新增的工作流技能。


范围验证、框架构建与分阶段设计对话

对于创建或取代操作,这是一道硬性关卡:在向工程师提出任何一个设计问题之前,完整阅读 internal/design-conversation.md 并遵循它。 其中包含范围验证(包括已构建的文档路径)、框架构建以及分阶段设计对话。上文的询问与行动只是意图,而非协议;在你读完该文件之前,不要开启访谈、生成问题或编写规范。(仅就地更新规范时可跳过。)

编写规范(主线程)

在分阶段对话之后,由你自己编写规范。不要指派任何人来起草、研究或评审它。将此技能的文件夹解析为绝对路径(你已经在解析这些相对路径,所以你知道该文件夹),并立即阅读三个文件(只有现在读,这样它们就不会在访谈期间一直留在上下文中):agent-prompt.md、spec-template.md,以及与推断出的 MODE 匹配的那个模式文件:

  • FEATURE → agent-modes/feature.md
  • ARCHITECTURE → agent-modes/architecture.md
  • ENHANCEMENT → agent-modes/enhancement.md
  • CROSS-CUTTING → agent-modes/cross-cutting.md

然后编写规范,并应用以下内容:

  • 来自 agent-prompt.md:采用其人格设定(“你是谁 / 你如何思考 / 你不做什么”),并遵循其通用说明、Step 0、Step 0b、## Expert rules that apply to all modes 以及 ## Report format。在 ## Instructions by mode 处,仅将上述那个模式文件作为唯一的模式专用块来遵循;忽略其他模式文件。agent-prompt.md 是作为带有 ALL_CAPS 占位符的子 Agent 简报编写的;将这些占位符理解为你在对话中已经收集到的输入(见下文),并将这些规则应用于你自己。
  • 来自 spec-template.md:仅使用 === SPEC TEMPLATE START === 与 === SPEC TEMPLATE END === 之间的部分(即规范章节结构与字段指导)。末尾的参考/元数据章节(## Filename conventions、## Status values 表格、总括结构 / 子状态说明、## Writing rules)是你自己的指导:你已在预检中解析出文件名、形态和初始 **Status**:;按照 ## Expert rules that apply to all modes 中“On the initial **Status**: line”规则编写 **Status**: 行。不要编辑 spec-template.md。 参考资料和链接:复用 Stage (c) 的 REFERENCES_LEVEL;现在不要获取。 按照 agent-prompt.md 中的 On sourcing & citations,在该级别撰写 ## References 部分和 (basis: ...) 引用。Stage (c) 的检查已运行一次;仅复用其确认过的链接,并对任何未经验证的来源只注明名称,不附 URL。只有在 Stage (c) 从未运行过(例如文档路径)时,才在此时展示 References 同意面板(建议选择 No references, keep it clean),并将 REFERENCES_LEVEL 设为 none 或 sources(不提供 sources+links,撰写时无法获取资料)。

推断出的 MODE(来自 Framing)已是 FEATURE / ARCHITECTURE / ENHANCEMENT / CROSS-CUTTING 之一。

需要应用的输入(你已从设计对话和预检中获得):

  1. 设计主题(来自用户的原始消息)
  2. 推断出的框架:MODE、平台(web/mobile/API)、技术栈与约定(来自 AGENTS.md),以及推断或确认的任何约束/合规要求 2a. 功能的构建方案(预检优先级:范围行中的 Approach 覆盖项,否则采用 AGENTS.md / 范围标题中的项目默认值,再否则采用注明的默认值)→ BUILD_APPROACH;根据该方案对功能的要求安排 ## Build plan 的顺序和切片
  3. 分阶段记录的所有对话答案:已确认的验收标准(已有 AC-1… 等 ID,用于填充 ## Requirements)、已确认的数据模型(实体/字段/关系,用于确定 ## Build plan 的迁移目标,范围应与功能匹配)、已确认的技术栈/工具选择、API 表面、授权模型和边缘情况。在文档路径上(跳过分阶段对话时),应视为 "Staged design skipped, documenting an already-made decision",而非错误 3a. RECOMMEND 项目 → RECOMMEND_ITEMS_OR_NONE:必须做出并说明理由的具体决策(与技术栈一致的工具/提供方、会话模型等);逐项做出选择,不要将其原样作为开放问题重复提出。如无此类项目,则视为 "none" 3b. References 级别 → REFERENCES_LEVEL(none | sources | sources+links,遵循上方规则)。如果 Stage (c) 从未运行过且尚未询问,则默认为 none
  4. 上下文文件内容:AGENTS.md(根目录及功能区域的嵌套文件),或在其不存在时使用 CLAUDE.md,否则填写 "MISSING"
  5. 现有规范列表(文件名及每个文件的首行)
  6. 相关规范路径(预检中标记的路径)
  7. 已确定的规范位置($SPEC_DIR)、下一个编号及结构:单个文件 $SPEC_DIR/NNNN-title.md,或目录 $SPEC_DIR/NNNN-title/(包含 index.md + rationale.md,总规范还包括子规范)。总规范:撰写已命名的子决策;任何清单/审计内容都放入 rationale.md,绝不放入 docs/scope/,也不要散落在代码树中。只有 index.md 包含 **Status**: 行(与功能状态一致);子规范不写生命周期 Status(规范内容由总规范管理)
  8. 源文件数量(是否有代码可读;对于大型 ENHANCEMENT / CROSS-CUTTING 代码库,应按 Subagents 的说明将代码阅读交由 scout 子代理,并根据其梳理结果撰写)
  9. 操作:create | update | supersede
  10. 今天的日期(来自预检)
  11. 文档上下文(如果执行了“已构建”路径:工程师对于选择原因、备选方案和权衡的自由文本回答)
  12. 与此功能相关的社区技能(根据预检从 AGENTS.md 中识别):仅在技能会对该决策产生实质影响时,才按需打开技能文件;查阅后,其约定具有权威性。在 ## Decision 的 Implementation skills 字段中逐一列出。

规范撰写完成后

规范文件创建后,读取 internal/after-subagent.md,并遵循其中的说明,自行检查和审阅规范、确认内容、批准状态、关联范围,并完成最终口头总结。撰写规范之前不要读取该文件。

更新 / 取代路径

如果任务是更新或取代现有规范:

  • 预检:完整阅读现有规范
  • 如果是原位更新操作,则跳过分阶段对话
  • 设置操作:update 或 supersede
  • 如果是取代:编写新规范,并将旧规范的状态更新为 Superseded by [NNNN](NNNN-title.md)
批准暂定决策

当主题对应一份现有的 Assumed 规范时(工程师先通过 /develop 的例外通道完成构建,现在要正式批准,通常会表述为 /architect <feature>: ratify …),预检会找到该规范。请完整阅读:其中的 ## Owed decision、## Assumption built on 和 ## Code area 会说明暂定决定的内容以及代码所在位置。然后围绕实际已构建的内容,进行常规设计对话,并认真审议该决定。结果有两种:

  • 假设成立。 补全实际决策内容(Context、Options considered、Decision、Rationale、设计部分和 Consequences),使规范成为经过正式审议的记录,并清除 Assumed:将 **Status**: 行设为该功能生命周期中的状态(如果功能已构建但尚未 done,则设为 In Progress;如果已经过验证和测试,则设为 Accepted)。与往常一样,/develop 会在功能达到 done 时将其状态关闭为 Accepted。该决策不再是临时决定。
  • 假设有误。 编写一份修正后的规范(create 或 supersede),记录实际决策,并将暂定规范标记为 Superseded by [NNNN](…);同时告知工程师,当前构建基于错误假设,应根据修正后的规范重新构建。

无论哪种结果,批准流程都能让 Assumed 规范退出该状态:/develop 记录假设,/architect 确认或纠正该假设并说明理由。批准流程结束后,不要让规范继续处于 Assumed 状态。


参考文件

  • 规范模板:spec-template.md(主线程在写入时读取)
  • 规范编写规则与角色设定:agent-prompt.md(主线程在写入时读取)
  • 模式专属编写说明:agent-modes/*.md(仅在写入时读取匹配的模式文件)
  • 主线程设计对话:internal/design-conversation.md(仅在 create/supersede 时读取)
  • Agent Skill 与 MCP 工具推荐:internal/tool-discovery.md(仅当技术栈梳理确定需要新增工具时读取;它会先询问,再由 researcher 子 Agent 执行注册表查询)
  • 主线程完成流程:internal/after-subagent.md(仅在规范写入后读取)
  • 分阶段设计对话按功能生成(参见 分阶段设计对话,阶段 a 到 f),不会存储;没有预设问题列表。如果主题过于模糊而无法生成对话,应先缩小范围(验证范围,或提出一个澄清问题),绝不要退回通用选择题

评论

支持 Markdown