Implementation Plan: [FEATURE]-平芜编程栈

Implementation Plan: [FEATURE]

【免费下载链接】spec-kit💫 Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit

Branch:[###-feature-name]|Date: [DATE] |Spec: [link]

Input: Feature specification from/specs/[###-feature-name]/spec.md

Note: This template is filled in by the__SPECKIT_COMMAND_PLAN__command; its definition describes the execution workflow.

几个值得注意的设计点： - **输入契约显式化**：`Input` 行规定 plan 的唯一输入来源是对应特性目录下的 `spec.md`，把“先规格、后设计”的依赖关系固化在文档头部； - **元信息三件套**：分支号 `[###-feature-name]`、日期、规格链接，构成每个特性目录的可追溯标识（分支编号规则与 [spec-template.md](https://link.gitcode.com/i/8d778f5558c27510e244f7b8b03bfcf5) 保持一致）； - **`__SPECKIT_COMMAND_PLAN__` 占位符**：这类双下划线包裹的命令名（如 `__SPECKIT_COMMAND_PLAN__`、`__SPECKIT_COMMAND_TASKS__`）在安装到具体 Agent 集成时会被替换为实际的斜杠命令（如 `/speckit.plan`），替换规则可见 [src/specify_cli/integrations/base.py](https://link.gitcode.com/i/afd9824ea0ea338c50b13076877591f8) 的注释。这样模板文本本身无需绑定任何特定 Agent 的命令格式。 ## 二、模板逐节详解 以下按 [plan-template.md](https://link.gitcode.com/i/8223e9155e4bba1e1e879e7bcf1cae51) 的实际章节顺序逐节说明，所有字段均完整保留，可直接对照复制。 ### 2.1 Summary ```markdown ## Summary [Extract from feature spec: primary requirement + technical approach from research]

摘要节要求从spec.md中提取“核心需求 + 调研得出的技术路线”一句话概括。它不是自由发挥区，而是强制把设计结论与规格需求绑定，便于后续审计“设计是否偏离规格”。

2.2 Technical Context（技术上下文）

这是模板中信息密度最高的一节，以 HTML 注释开头，提示填写者该节结构是“建议性的（advisory）”，可随项目调整：

**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION] **Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION] **Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A] **Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION] **Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION] **Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION] **Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION] **Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION] **Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]

九个字段覆盖了语言版本、主依赖、存储、测试框架、目标平台、项目类型、性能目标、约束条件和规模范围。其中最关键的机制是NEEDS CLARIFICATION标记：

任何一时无法确定的字段必须显式写NEEDS CLARIFICATION，而不是猜测一个值；
这个标记是后续 Phase 0 调研阶段的“任务清单来源”——plan 命令明确规定：每个NEEDS CLARIFICATION都转化为一条调研任务，每个依赖项生成最佳实践调研任务，每个集成点生成模式调研任务，最终所有标记必须在research.md中被解决（“Output: research.md with all NEEDS CLARIFICATION resolved”）；
命令的 Key rules 进一步规定“ERROR on gate failures or unresolved clarifications”，即带未解决标记的 plan 不允许流转到下一阶段。

2.3 Constitution Check（宪法门禁）

## Constitution Check *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* [Gates determined based on constitution file]

该节是 plan 阶段的“准入与复验”双重门禁：

进入 Phase 0 前必须通过：依据.specify/memory/constitution.md中定义的项目宪法（工程原则、架构约束、质量底线）逐条比对，存在违规即报错终止（plan 命令 Outline 第 3 步：“Evaluate gates (ERROR if violations unjustified)”）；
Phase 1 设计完成后复验：设计可能引入新的架构决策，需要再次对照宪法确认没有越界。

注意门禁的具体条目“由宪法文件决定”，模板本身不硬编码任何规则——这正是 Spec Kit 的“组织约束可配置”思想：把团队的架构红线写进宪法，plan 模板只负责在两个关键节点强制检查。

2.4 Project Structure（项目结构）

该节分两部分。

（1）本特性的文档树——固定结构，说明 plan 阶段会在特性目录下产出/维护哪些文件：

specs/[###-feature]/ ├── plan.md # This file (__SPECKIT_COMMAND_PLAN__ command output) ├── research.md # Phase 0 output (__SPECKIT_COMMAND_PLAN__ command) ├──>**Structure Decision**: [Document the selected structure and reference the real directories captured above]

即必须写明选择了哪种结构、对应仓库中哪些真实目录。这使 plan.md 成为后续/speckit.tasks拆分任务时定位文件的依据。

2.5 Complexity Tracking（复杂度追踪）

## Complexity Tracking > **Fill ONLY if Constitution Check has violations that must be justified** | 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] |

这是“越级审批表”：只有当宪法门禁存在必须正当化的违规时才填写，每行三列分别记录违规内容、为什么需要、以及更简单方案被否决的理由。它把“设计复杂度”从隐性决策变成了可评审、可回溯的显性记录——后续维护者可以从这张表看到当初为什么没有选择更简单的方案。

三、模板如何变成 plan.md：setup-plan 脚本

/speckit.plan命令并不自己拷贝模板，而是先运行 setup 脚本。plan 命令的 frontmatter 声明了三个平台等价实现：

scripts: sh: scripts/bash/setup-plan.sh --json ps: scripts/powershell/setup-plan.ps1 -Json py: scripts/python/setup_plan.py --json

以 setup_plan.py 为例，其执行逻辑：

通过 common.get_feature_paths() 解析出FeaturePaths：特性目录、spec.md、plan.md、research.md、data-model.md、quickstart.md、contracts/等路径——特性目录优先读取环境变量SPECIFY_FEATURE_DIRECTORY，否则回退到.specify/feature.json中记录的feature_directory（通常由create-new-feature脚本在/speckit.specify阶段写入）；
若plan.md已存在则跳过（幂等），否则调用resolve_template_content("plan-template", repo_root)取模板内容写入specs/[###-feature-name]/plan.md；
以--json模式输出单行 JSON（状态信息走 stderr，保证 stdout 是纯 JSON）：

{"FEATURE_SPEC": ".../spec.md", "IMPL_PLAN": ".../plan.md", "SPECS_DIR": ".../specs/001-xxx", "BRANCH": "001-xxx"}

【免费下载链接】spec-kit💫 Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Implementation Plan: [FEATURE]