technical-planning

技术规划

核心原则

关注“做什么”，而非“怎么做”：定义可交付成果，而非实现细节。明确约束和成功标准，但为实现方式留出灵活空间。

在最后一个负责任的时机做决定：等到掌握足够信息后再做决定，以便做出明智选择，但不要拖到阻碍进度。快速做出可逆的决定；将不可逆的决定推迟到确有必要时再做。

风险优先开发：优先解决风险最高的技术挑战。在完整实现前先构建概念验证。尽早交付可用但不完美的解决方案，以验证核心假设。

有计划地推迟：明确记录哪些事项会推迟，以及何时处理。区分核心价值交付与打磨／优化。

使用 TodoWrite 跟踪进度

使用 TodoWrite 跟踪规划的四个阶段：

1. 开始时：为每个阶段创建待办事项：

   ☐ Phase 1: Requirements & Risk Analysis
   ☐ Phase 2: Milestone Planning
   ☐ Phase 3: Implementation Strategy
   ☐ Phase 4: Execution Framework
   

2. 规划期间：在推进各阶段时，将其标记为 in_progress → completed。为关键交付物添加子待办事项：

   ☐ Extract core requirements (2-3 user journeys)
   ☐ Identify technical risks (high/integration/performance/architecture)
   ☐ Define milestones with success criteria
   ☐ Document deferred items with rationale
   

3. 对于复杂项目：将待澄清的问题及其解决情况作为待办事项跟踪，避免在信息不完整时继续推进

决策时机框架

尽早决定（需求阶段）：

• 要解决的用户问题
• 成功标准和衡量方式
• 硬性约束（安全、合规、性能 SLA）
• 关键集成和依赖项
• 会影响架构的技术选择

推迟到实施阶段（执行阶段）：

• 具体算法或数据结构
• 内部 API 设计细节
• 代码组织模式
• 库的选择（有多个可行选项时）
• 性能优化（证明确有必要后再做）
• UI／UX 细节（用户测试后再确定）

原因：早期决策应当推动工作开展，而不锁定具体细节。通过亲自实践，实施决策会变得更加清晰，也往往能发现比预先规划所设想的更好的替代方案。

Agent 指南

先厘清，再推进：切勿对不明确的需求、技术约束或业务优先级妄下假设。只有在对关键方面的把握达到 80% 以上时才继续。针对以下事项提出具体问题：

• 要解决的用户问题（而不仅是用户提出的功能）
• 成功标准和衡量方法
• 技术约束和现有系统依赖项
• 团队能力和技术偏好
• 时间限制和优先级权衡
• 性能和可扩展性要求

阶段 1：需求与风险分析

前置条件检查

确认：

• 要解决哪些用户问题？
• 主要用户是谁？他们的工作流是什么？
• 如何衡量成功？
• 有哪些技术和业务约束？

提取核心需求

1. 确定要解决的根本用户问题
2. 梳理主要用户旅程（聚焦于 2-3 条关键路径）
3. 定义项目成功指标

识别技术风险

1. 高影响风险：可能导致方案失效的技术未知因素
2. 集成风险：外部系统依赖项和兼容性问题
3. 性能风险：可扩展性瓶颈和算法挑战
4. 架构风险：影响范围广泛的根本设计决策

风险优先级矩阵

• 关键且未知：必须在里程碑 1 中通过概念验证解决
• 关键且已知：在早期里程碑中使用成熟模式解决
• 非关键：推迟到后续里程碑处理或直接消除

阶段 2：里程碑规划

前置条件检查

确认：

• 阶段 1 中识别的技术风险优先级
• 团队产能和可用时间
• 不同组件之间的依赖关系
• 本项目中“可用功能”的定义

里程碑结构

• 时间安排：根据项目复杂度，采用 4-8 周的周期
• 交付成果：每个里程碑都必须产出可运行、可测试的功能
• 风险重点：安排里程碑顺序时，优先处理风险最高的事项

为每个里程碑定义：

目标：用一句话描述里程碑的成果

核心任务：遵循「最后负责时刻」原则的 4-6 项主要实施任务：

• 明确成果和约束
• 确认依赖项和集成点
• 提供背景和注意事项（而非逐步操作说明）
• 保持实施细节的灵活性
• 标记执行过程中需要解决的问题

成功标准：

• 最低可行成功（完成里程碑必须达成）
• 完全成功（理想成果，包括完善工作）

风险缓解：列出需要在此里程碑中解决的具体未知项

延期事项：有意暂不纳入的事项，以及计划在哪个里程碑中纳入

任务拆分指南

拆分任务时，应提供指导而非规定：

✓ 良好的任务定义（以成果为导向）：

• 目标：「让用户能够安全地进行身份验证」
• 约束：「必须与现有会话中间件集成；响应时间低于 100ms」
• 指导：「考虑使用会话还是令牌身份验证；查看 src/middleware/ 中的现有模式」
• 验证：「用户可以登录，会话能够持久化，测试通过」

✗ 不佳的任务定义（规定过多）：

• 步骤 1：「创建文件 auth.js 并导入 bcrypt」
• 步骤 2：「使用 bcrypt.hash（10 轮）编写 hashPassword 函数」
• 步骤 3：「创建一个检查 req.session.userId 的 Express 中间件」

原因：良好的定义让实施者能够根据实际了解的情况选择最佳方案。不佳的定义会在尚未了解背景时就锁定方案，往往导致返工。

里程碑定义示例

目标：验证用户身份验证，并通过外部 API 检索基本数据

核心任务：

1. 使用服务提供方实现 OAuth 流程
2. 创建用户会话管理
3. 构建带错误处理的 API 客户端
4. 添加基本的用户个人资料展示

成功标准：

• 最低要求：用户可以登录并查看个人资料数据
• 完全成功：包含个人资料编辑和会话持久化

风险缓解：确认 API 速率限制以及负载下的响应时间

延期事项：高级个人资料功能、密码重置流程（里程碑 3）

阶段 3：实施策略

开发方法

• 先构建原型：制作一次性版本，以验证高风险假设
• 先核心功能，再完善细节：先实现功能，再优化 UI
• 尽早集成：在第一个里程碑中测试与外部系统的连接
• 持续度量：从第一天起跟踪性能和用户指标

技术选型标准

1. 团队专长：优先选择团队熟悉的技术
2. 可靠性验证：核心系统选择成熟、经过实战检验的方案
3. 集成能力：确保与现有工具/系统兼容
4. 扩展路径：技术应能支持预期的增长

质量门槛

• 所有代码都必须具备基本测试覆盖率
• 核心用户流程必须达到性能基准
• 身份验证和数据处理必须经过安全审查
• 面向用户的功能必须符合无障碍标准

阶段 4：执行框架

冲刺规划

1. 风险评估：识别即将开展的工作中的未知项
2. 探索时间：预留 20-30% 的冲刺时间用于原型开发/学习
3. 完成定义：必须包含可运行的功能，而不只是完成代码
4. 持续验证：定期收集利益相关方对核心用户流程的反馈

延期管理

• 定期审查：每个里程碑都评估延期事项，确认其是否仍然相关
• 分类：技术债务、UX 润色、边缘情况、性能优化、高级功能
• 安排：将延期事项规划到合适的后续里程碑
• 取消：部分延期事项可能不再需要

文档要求

• 聚焦于交付成果的技术规范
• 包含缓解计划的风险登记表
• 包含目标排期的延期事项登记表
• 重大决策的架构决策记录

面向 Agent 的决策框架

如果 项目的技术可行性未知 → 在里程碑 1 中安排概念验证 如果 项目需要外部集成 → 在第一个里程碑中测试最小化集成 如果 项目有性能要求 → 尽早建立基准并测试核心算法 如果 团队缺乏所选技术方面的专业知识 → 在早期里程碑中安排学习和探索时间 如果 项目期限紧迫 → 聚焦于最低可行成功标准，并将润色工作延期 如果 项目是绿地项目 → 投入更多时间进行架构决策和基础设置 如果 项目是增强项目 → 聚焦于集成点和向后兼容性

不确定时——请提出这些问题

当 需求模糊时 → “这要解决什么具体的用户问题？我们将如何衡量成功？” 当 技术范围未定义时 → “哪些技术能力是必需的，哪些是锦上添花？” 当 时间安排不切实际时 → “哪些截止日期不可更改？时间安排有哪些灵活性？” 当 团队能力未知时 → “团队熟悉哪些技术？技能差距在哪里？” 当 集成点不明确时 → “必须连接哪些现有系统？数据格式和 API 有哪些限制？” 当 性能需求未明确时 → “预期的用户负载和响应时间要求是什么？” 当 缺少成功标准时 → “我们如何判断这个里程碑已完成并取得成功？”

应避免的常见陷阱

• 需求不明确时，擅自假设，而不是提出澄清问题
• 在信息不完整时继续推进，而不是索取必要的详细信息
• 制定过于死板的任务定义，提供逐步说明，而不是聚焦于结果的指导
• 过早做出实施决策，而这些决策本可以留待执行阶段
• 花时间处理低风险功能，却将关键的未知事项延期
• 尚未验证核心假设，就过度设计解决方案
• 规划实施细节，而不是聚焦于交付成果
• 猜测用户需求，而不是了解要解决的具体问题
• 未记录延期决策及其理由
• 尚未证明核心功能，就过早进行优化
• 在了解完整背景之前就敲定技术选型