学习指南: 第10部分：项目重新规划

模块「第10部分：项目重新规划」中第 2 / 5 节课

您正在未登录状态下查看课程。请登录，以保存进度并参加测试。

主题：第10部分项目重新规划

难度级别：中级

预计学习时间：3-4小时（理论+实践）

先决条件： Git基础操作（分支、合并、提交）

理解SDD项目文档结构（mission.md、tech-stack.md、roadmap.md）

具备Hono框架的基础使用经验

理解功能规格说明（feature specs）的概念

具备TypeScript和测试的基础知识

学习目标：独立执行功能之间的重新规划阶段，创建独立的Git分支并更新项目文档

确定功能实现中的哪些观察结果应当编码为规则（QWEN.md）、技术决策（tech-stack.md）、验证模板（validation.md）或代理技能

向AI代理提出更新规格说明、变更日志和路线图的请求，而不实现新的产品功能

根据可验证性和价值标准评估路线图阶段的大小，避免过宽或过细的迭代

概述：项目重新规划是SDD（规范驱动开发）方法论中的关键阶段，它在功能实现之间进行，而非在功能实现内部进行。这是一个有意识的暂停时刻，团队在此固化获得的知识、更新项目文档，并将一次性观察转化为永久性规则。AI代理生成代码的速度越快，就越需要定期回归项目章程并在偏差尚小时修正航向。重新规划回答五个关键问题：我们学到了什么、是否需要更新技术栈、路线图是否仍然适用、哪些验证应成为强制要求、以及哪些流程值得自动化。成功的重新规划创建反馈飞轮：前一个功能的每次观察都会触发规则更新，从而降低在下一次迭代中重复相同问题的概率。

核心概念：重新规划阶段：功能完成后创建的独立Git分支，专门用于更新项目文档而不实现新的产品功能。与普通开发的区别在于禁止编写新功能代码——聚焦于反思和编码固化。

观察编码：将功能实现中的一次性观察转化为项目永久性产物的过程。四种产物类型：代理行为规则（QWEN.md）、技术决策（tech-stack.md）、验证模板（validation.md）、可自动化的技能和钩子（.qwen/skills/）。

变更日志changelog.md：按日期记录的文档，作为项目的人类可读简史和AI代理的上下文。基于Git历史和当前分支的变更创建，而非从零手动编写。

测试策略：tech-stack.md中的形式化要求，确定工具（Vitest）、运行命令（npm test）以及在功能规格说明中注明自动验证的强制性。

自适应设计作为项目规则：项目级别的要求，而非单独功能的要求：页面必须在375px移动端宽度和1280px桌面端宽度下正常工作。编码固化后追溯应用于所有现有规格说明。

路线图阶段大小：可验证性标准：阶段不应过宽（"构建所有功能"）或过细（"添加一个CSS内边距"）。最佳阶段具有具体的领域目标和3-5个可验证的任务。

反馈飞轮：持续改进模型，其中功能实现的每个信号（代理重复错误、未找到文件、错误测试）都有预定义的响应记录位置。如果找不到位置——则表明项目结构中缺少相应部分。

旧规格说明更新：将已完成的功能规格说明调整为新的项目规则而不改变实现的过程（如果更新后的验证不要求）。保持历史准确性：规格说明解释实现时生效的规则。

重新规划分支：独立的开发线（例如replanning-after-hello-hono），从main分支开始，仅包含文档变更，并在测试和类型检查通过后通过合并回归。

练习：标题：创建重新规划分支并构建请求

问题：您在Hono + TypeScript项目中完成了第一个功能"Hello Hono"。观察结果：代理两次忘记在提交前运行测试；设计在手机上显示不佳；规格说明中没有"验证"部分；您三次要求代理在开始工作前阅读mission.md。创建重新规划分支并构建向代理提出的请求，更新项目文档而不实现新功能。

解答：1. 创建分支：git checkout -b replanning-after-hello-hono

构建带有明确限制的请求：

/clear 阅读 @specs/mission.md、@specs/tech-stack.md、@specs/roadmap.md 和已完成的功能规格说明Hello Hono。我们正在执行重新规划阶段。不要实现新的产品功能。为以下方面提出变更建议：

提交前强制运行的测试策略；
作为通用要求的自适应设计（375px/1280px）；
功能规格说明中的验证模板；
通过技能自动阅读mission.md。

修改前请先列出建议变更的文件。

验证请求是否包含明确禁止新功能的要求以及变更预列表。

难度：初级

标题：将观察结果编码到正确的产物中

问题：完成"Hello Hono"功能后，您记录了6项观察。将它们按产物类型分类并解释选择： (a) 代理未经许可修改tsconfig.json导致构建失败 (b) Vitest比手动测试更方便 (c) 数据库迁移未验证重复运行的幂等性 (d) 请求"按模板Y生成功能X的规格说明"使用了5次 (e) 代理找不到项目中的常量文件 (f) 实现添加了requirements.md中没有的"status"字段

解答：1. (a) → QWEN.md（代理行为规则）："未经人工确认不得修改tsconfig.json"

(b) → tech-stack.md（技术决策）："所有测试使用Vitest，npm test运行vitest run"
(c) → validation.md（验证模板）："迁移需通过重复运行验证幂等性"
(d) → .qwen/skills/spec-generation/SKILL.md（技能）：将带功能参数的查询自动化
(e) → QWEN.md（扩展"初始阅读清单"）：添加常量文件
(f) → 通过重新规划分支更新requirements.md（反向追溯）：事后固化决策
理由：选择取决于观察的性质——代理行为、技术选择、验证形式、机械重复、项目结构、需求。

难度：中级

标题：评估和修正路线图

问题：分析路线图第二阶段的三个方案并确定哪个符合良好阶段标准。为不正确方案提出修正：

方案A：

第二阶段：构建整个应用

[ ] 添加数据库
[ ] 完成所有页面
[ ] 编写测试

方案B：

第二阶段：在Hello Hono标题中添加padding-top

[ ] 修改CSS

方案C：

第二阶段：代理与疾病

目标：添加基础领域模型和只读页面。

[ ] 添加代理和疾病的SQLite模式。
[ ] 添加初始虚构数据。
[ ] 添加 /agents 和 /ailments 页面。
[ ] 添加路由和组件测试。

解答：1. 方案A——过宽。问题："整个应用"不可验证；"所有页面"不具体；变更量使人工审核困难。修正：按领域边界拆分为2-3个阶段（例如"代理与疾病"、"申请与分配"、"管理"）。

方案B——过细。问题：分支、代码审查、合并的开销超过价值；没有领域意义。修正：与其他CSS任务合并为"基础布局和导航"阶段，或作为更大阶段的子任务。
方案C——正确。验证：具体的领域目标（"基础领域模型"）；4个可验证任务；明确边界（"只读"）；可衡量的结果（4个复选框）。
通用原则：阶段应"可在一个晚上验证"并承载领域价值。

难度：中级

标题：创建CHANGELOG.md并通过代理更新

问题：完成包含tech-stack.md、validation.md和roadmap.md变更的重新规划分支后，构建向代理提出创建或更新CHANGELOG.md的请求。原始数据：分支创建于2026-05-01，提交包含添加Vitest、自适应设计规则、明确路线图第2-3阶段。

解答：1. 向代理提出的请求： /clear 创建或更新 @CHANGELOG.md。使用YYYY-MM-DD格式的日期标题。基于replanning-after-hello-hono分支的Git历史和当前分支变更。为相关人员写得简洁明了。每个要点应为单行，以动词开头。

预期结果：

# 变更日志 ## 2026-05-01

添加Vitest测试策略（npm test → vitest run）。
引入自适应设计要求（375px/1280px）。
按领域明确路线图第2和第3阶段边界。
更新功能规格说明模板，添加"强制验证"部分。

验证：日期与提交对应，要点原子化，语言面向人类但结构便于代理解析。

难度：初级

标题：应用反馈飞轮

问题：在实现"代理与疾病"功能过程中发生以下事件。为每个事件确定更新哪个产物，或记录项目结构中缺少部分：

代理生成的迁移在相同数据库重复应用时失败
代理找不到领域模型类型文件，尽管它位于/src/types/
人员注意到/agents页面在iPhone SE上显示不正确，尽管测试通过
代理三次询问应使用哪种API响应格式
功能规格说明中意外包含真实客户姓名示例

解答：1. 迁移重复失败 → validation.md：新模板"迁移需通过重复运行验证幂等性"（验证级别提升）。

未找到/src/types/中的文件 → QWEN.md：扩展"初始阅读清单"指明目录结构；可能添加规则"创建类型前先检查/src/types/中的现有文件"。
测试通过但实际行为错误 → validation.md：添加事实"数据页面除功能测试外，需在375px宽度验证渲染"；可能引入视觉验证级别（见第9部分）。
三次询问API格式 → .qwen/skills/api-response-format/SKILL.md：固化响应标准（JSON、字段、错误码）。
规格说明中的真实姓名 → QWEN.md：规则"示例中不得使用真实客户数据" + validation.md：PII检测验证场景（见第18部分）。
验证：所有5个案例在现有结构中找到位置——说明结构适当。如某观察找不到位置，则是创建新部分的信号。

难度：高级

案例研究：标题：医疗平台首个功能后的重新规划

场景：由两名开发人员和产品经理组成的团队为内部患者管理平台实施SDD。首个功能"Hello Hono"——带JSX服务端渲染的基础欢迎页面——借助Qwen Code AI代理在2天内完成。团队准备立即进入"患者注册"功能。

挑战：产品经理注意到欢迎页面在他的iPhone 12 mini（375px宽度）上显示不正确，尽管桌面端正常。开发人员A发现代理忘记在最终提交前运行测试，不得不手动修复TypeScript错误。开发人员B三次向代理提出相同请求："阅读mission.md，然后按specs/templates/中的模板为功能X生成规格说明"。路线图包含第二阶段："实现整个患者模块"而无细化。团队意识到没有反思暂停，下一个功能将重复相同问题。

解决方案：团队创建replanning-after-hello-hono分支并执行4小时的重新规划阶段。向代理的请求包含明确禁止实现新功能。行动顺序：(1) 代理分析已完成的Hello Hono规格说明并提出变更建议；(2) 在tech-stack.md中添加Vitest测试策略（强制npm test）和自适应设计要求（375px/1280px）；(3) 在validation.md中引入"页面需在移动端宽度验证渲染"模板；(4) 创建项目历史的CHANGELOG.md；(5) 将第二阶段拆分为"患者：读取"（模式、页面、测试）和"患者：写入"（表单、验证、安全）；(6) 将重复请求编码为.qwen/skills/spec-generation/SKILL.md技能。旧规格说明按新规则更新而不改变实现。

结果：实现"患者：读取"功能时手动修复时间减少60%。代理自动运行测试并检查自适应性。规格说明通过单次技能调用生成，替代三次请求迭代。阶段人工审核耗时2小时，而非预期的一体化阶段6小时。CHANGELOG.md使一个月后加入的新开发人员能在15分钟内理解项目历史。

经验教训：功能之间的重新规划通过预防错误重复节省的时间超过其本身耗时

将重复请求编码为代理技能对每个后续功能产生乘数效应

项目级别的自适应设计要求比单独修复每个页面更经济

将一体化阶段拆分为可验证迭代降低审核人员的认知负荷

变更日志不仅对人类有用，也作为未来向代理提出请求的上下文