ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

AionUi 基于 `/plan` 命令的功能实现计划模板解析:规范驱动的 AI 协作开发工作流

AionUi 基于 `/plan` 命令的功能实现计划模板解析:规范驱动的 AI 协作开发工作流 AionUi 基于/plan命令的功能实现计划模板解析规范驱动的 AI 协作开发工作流【免费下载链接】AionUi免费、本地、开源的 24/7 全天候 Cowork 应用以及适用于 Gemini CLI、Claude Code、Codex、OpenCode、Qwen Code、Goose CLI、Auggie 等的 OpenClaw | 喜欢就点star吧项目地址: https://gitcode.com/iOfficeAI/AionUi导读本文以 AionUi 仓库中 .specify/templates/plan-template.md 为绝对核心完整解析这份「功能实现计划Implementation Plan」模板的结构、执行流程、闸门Gate机制与各阶段产出物。读完本文你将掌握 AionUi 所采用的「规格文档 → 计划 → 任务 → 实施」四阶段 AI 协作开发流水线中/plan命令的设计逻辑理解如何用技术上下文Technical Context、宪法检查Constitution Check、复杂度追踪与进度追踪把一次模糊的功能需求收敛为一份可执行的、符合项目约束的落地方案并知晓它与同目录下 spec、tasks、agent 模板的协作关系。模板定位一次功能从规格到计划的「安检通道」在 AionUi 的 AI 协作开发体系中功能落地被拆分为若干可编排的命令阶段而.specify/templates/plan-template.md是其中/plan命令的输出格式与执行蓝图。它接收来自 .specify/templates/spec-template.md 生成的特性规格文档Feature Spec经过一套带错误退出路径的九步编排最终产出plan.md本模板自身即/plan命令输出research.mdPhase 0 输出data-model.md、quickstart.md、contracts/Phase 1 输出并明确不创建tasks.md——那是后续/tasks命令的职责。模板头部给出了每份计划文件的元信息约定这是后续所有阶段追溯需求的锚点# Implementation Plan: [FEATURE] **Branch**: [###-feature-name] | **Date**: [DATE] | **Spec**: [link] **Input**: Feature specification from /specs/[###-feature-name]/spec.md其中[###-feature-name]是功能分支编号与功能名###为三位数字编号Spec链接指向对应功能的规格文档。这一约定与 spec-template.md 头部的**Feature Branch**: [###-feature-name]一一对应保证「分支名 ↔ 规格文档路径 ↔ 计划文档目录」三者在整个流程中始终一致。执行流程/plan命令的九步编排模板核心是一段带严格顺序与错误分支的执行流程伪代码它是/plan命令的运行时契约1. Load feature spec from Input path → If not found: ERROR No feature spec at {path} 2. Fill Technical Context (scan for NEEDS CLARIFICATION) → Detect Project Type from context (webfrontendbackend, mobileappapi) → Set Structure Decision based on project type 3. Fill the Constitution Check section based on the content of the constitution document. 4. Evaluate Constitution Check section below → If violations exist: Document in Complexity Tracking → If no justification possible: ERROR Simplify approach first → Update Progress Tracking: Initial Constitution Check 5. Execute Phase 0 → research.md → If NEEDS CLARIFICATION remain: ERROR Resolve unknowns 6. Execute Phase 1 → contracts,>## Constitution Check _GATE: Must pass before Phase 0 research. Re-check after Phase 1 design._ [Gates determined based on constitution file]其判定依据是「constitution file」。在当前仓库中这份文件就是 .specify/memory/constitution.md它定义了 AionUi 的五大核心原则多 AI 智能体集成、模块化架构优先、极致用户体验、安全与隐私优先、开发者体验与可维护性以及技术标准Electron 框架、React TypeScript、状态管理方案、开发工作流代码质量闸门、语义化版本、分支策略与治理规则架构决策、合规要求。宪法顶部即声明「Constitutional principles supersede implementation preferences」宪法原则优先于实现偏好——这正是模板把宪法检查设计为双向闸门的原因任何与宪法冲突的设计都必须被拦截、记录到复杂度追踪或直接报错简化方案。一个值得注意的细节plan-template 末尾标注_Based on Constitution v2.1.1 - See /memory/constitution.md_而仓库内 .specify/memory/constitution.md 当前版本为1.0.0ratified 2025-01-22。可以推断模板与其引用的宪法文档是独立版本化的使用者在套用模板时应以仓库实际宪法版本为准进行核对。项目结构规划文档产物与源码结构文档结构本功能模板规定了功能目录specs/[###-feature]/下的完整文档产出物及其归属命令specs/[###-feature]/ ├── plan.md # This file (/plan command output) ├── research.md # Phase 0 output (/plan command) ├──># Option 1: Single project (DEFAULT) src/ ├── models/ ├── services/ ├── cli/ └── lib/ tests/ ├── contract/ ├── integration/ └── unit/ # Option 2: Web application (when frontend backend detected) backend/ ├── src/ │ ├── models/ │ ├── services/ │ └── api/ └── tests/ frontend/ ├── src/ │ ├── components/ │ ├── pages/ │ └── services/ └── tests/ # Option 3: Mobile API (when iOS/Android detected) api/ └── [same as backend above] ios/ or android/ └── [platform-specific structure]结构决策规则是「DEFAULT to Option 1unless Technical Context indicates web/mobile app」——默认单项目布局仅当技术上下文明确指向 web 应用检测到 frontend backend或移动端检测到 iOS/Android时才切换为拆分布局。与仓库实际结构的印证有趣的是AionUi 仓库自身的结构恰好是「多包单仓」的变体packages/ 下并行存在 desktop、web-cli、web-host、shared-scripts 等独立包每个包内部又遵循src/tests/的布局如 packages/web-host/src 与 packages/web-host/tests移动端代码位于 mobile/其下同样拆分app/、src/、__tests__/。这说明模板的三选项结构是「最小通用骨架」真实项目可在其基础上按功能边界扩展——这并不冲突因为模板本身以「Structure Decision」字段显式记录最终选择。Phase 0研究阶段输出 research.mdPhase 0 的目标是把技术上下文中的所有未知项清零产出research.md。模板给出三步方法1. 提取未知项遍历 Technical Context 中的每个NEEDS CLARIFICATION、每个依赖、每个集成点分别映射为「研究任务」「最佳实践任务」「模式任务」。2. 分发研究 AgentFor each unknown in Technical Context: Task: Research {unknown} for {feature context} For each technology choice: Task: Find best practices for {tech} in {domain}3. 整合结论research.md强制使用「决策/理由/备选」三段式记录格式保证每个技术选型可追溯、可复议- Decision: [what was chosen] - Rationale: [why chosen] - Alternatives considered: [what else evaluated]Phase 0 的完成标准非常硬性所有NEEDS CLARIFICATION全部解决否则命令以ERROR Resolve unknowns中止。Phase 1设计阶段输出契约、数据模型、快速上手与 Agent 文件Phase 1 前置条件是research.md完成其产出覆盖四类工件1. 数据模型data-model.md从特性规格提取实体实体名、字段、关系、来自需求的校验规则以及如适用状态迁移。这一步直接对应 spec-template.md 中的「Key Entities」段落。2. API 契约contracts/从功能需求生成 API 契约每个用户动作映射为端点采用标准 REST/GraphQL 模式契约以 OpenAPI/GraphQL schema 形式输出到/contracts/目录。3. 契约测试先行失败每个端点对应一份契约测试文件断言请求/响应 schema并且测试必须处于失败状态Tests must fail (no implementation yet)——这是为后续 TDD 实施阶段准备的「红」起点。4. 测试场景提取从用户故事提取集成测试场景每个故事映射为集成测试场景quickstart 测试即故事的验证步骤。5. Agent 上下文文件的增量更新这是模板中唯一的显式命令且对执行方式有严格限定Run .specify/scripts/bash/update-agent-context.sh claude IMPORTANT: Execute it exactly as specified above. Do not add or remove any arguments.它要求以O(1)增量方式更新 Agent 上下文文件——只新增本次计划中的新技术保留标记之间的手工增补最近变更仅保留 3 条全文控制在150 行以内以节省 token输出到仓库根目录。这里的claude参数意味着按当前使用的 Agent 工具生成对应文件Claude Code 用CLAUDE.md、GitHub Copilot 用.github/copilot-instructions.md、Gemini CLI 用GEMINI.md、Qwen Code 用QWEN.md、opencode 用AGENTS.md。两点值得说明的事实性观察该 shell 脚本由工作流工具链提供当前仓库.specify/目录下.specify仅包含memory/constitution.md与四个模板文件并不包含.specify/scripts/bash/update-agent-context.sh本身模板所要求的输出形态与仓库根目录现有的 AGENTS.md 高度一致——后者正是「自动生成的开发指南」形态包含技术栈、项目结构、命令、代码风格、最近变更并保留了!-- MANUAL ADDITIONS START/END --手工增补标记区间与 agent-file-template.md 的标记设计完全吻合可以视作该模板在真实项目中的落地样例。Phase 2任务规划方法/tasks的职责预告Phase 2 明确标注「只描述/tasks 命令将做什么/plan期间不执行」。其核心策略包括任务生成以 tasks-template.md 为基础从 Phase 1 设计文档生成任务映射规则每个契约 → 契约测试任务[P]每个实体 → 模型创建任务[P]每个用户故事 → 集成测试任务以及让测试通过的实施任务排序规则TDD 顺序测试先于实现、依赖顺序模型 → 服务 → UI、独立文件的任务标记[P]以便并行执行产出预估tasks.md 中约25-30 个编号、有序的任务。模板再次强调「This phase is executed by the /tasks command, NOT by /plan」与执行流程第八步呼应。Phase 3未来实施阶段模板将后续阶段显式划出/plan的管辖范围**Phase 3**: Task execution (/tasks command creates tasks.md) **Phase 4**: Implementation (execute tasks.md following constitutional principles) **Phase 5**: Validation (run tests, execute quickstart.md, performance validation)注意 Phase 4 明确要求「遵循宪法原则」实施Phase 5 则把「运行测试、执行 quickstart.md、性能验证」作为收尾闸门——实施阶段同样受宪法约束。复杂度追踪为「必要的违反」留出记账位当宪法检查发现违规、但又必须保留时模板强制用表格记录「违规 → 为何需要 → 为何不接受更简单替代」例如| Violation | Why Needed | Simpler Alternative Rejected Because | | -------------------------- | ------------------ | ------------------------------------ | | [e.g., 4th project] | [current need] | [why 3 projects insufficient] | | [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |这是一套「先证明必要性、再记录在案」的治理机制不是禁止任何复杂度而是要求复杂度必须显式论证并保留审计痕迹。进度追踪贯穿全流程的核对清单模板末尾提供两份清单在执行流程各步骤中被增量勾选阶段状态- [ ] Phase 0: Research complete (/plan command) - [ ] Phase 1: Design complete (/plan command) - [ ] Phase 2: Task planning complete (/plan command - describe approach only) - [ ] Phase 3: Tasks generated (/tasks command) - [ ] Phase 4: Implementation complete - [ ] Phase 5: Validation passed闸门状态- [ ] Initial Constitution Check: PASS - [ ] Post-Design Constitution Check: PASS - [ ] All NEEDS CLARIFICATION resolved - [ ] Complexity deviations documented模板生态四个模板如何构成一条完整流水线plan-template 并非孤立文件它处于.specify/templates/四模板流水线的中间环节spec-template.md回答「用户要什么」WHAT WHY产出特性规格标记所有模糊点plan-template.md本文主体回答「如何规划」HOW to plan产出实施计划、研究结论、设计契约tasks-template.md把计划拆为编号任务T001…应用 TDD 顺序与[P]并行标记agent-file-template.md为各 Agent 工具维护长期记忆的开发指南文件通过update-agent-context.sh增量更新。而 .specify/memory/constitution.md 作为贯穿始终的「宪法」在规格评审、计划闸门、实施原则三个层面持续施加约束。这条「规格 → 计划 → 任务 → 实施 → 验证」的流水线配合仓库 AGENTS.md 中实际执行的 Conventional Commits、just push前置检查、prekCI 复刻等工程实践构成了 AionUi 面向 AI 协作开发的完整方法论需求先澄清、计划先受检、测试先失败、复杂度先论证。对任何希望把 AI 编程 Agent 纳入团队正规开发流程的开发者而言这份模板的设计尤其是命令边界划分与宪法闸门机制都是可直接借鉴的范本。【免费下载链接】AionUi免费、本地、开源的 24/7 全天候 Cowork 应用以及适用于 Gemini CLI、Claude Code、Codex、OpenCode、Qwen Code、Goose CLI、Auggie 等的 OpenClaw | 喜欢就点star吧项目地址: https://gitcode.com/iOfficeAI/AionUi创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表