Back to Details

technical-planning

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Technical Planning

技术规划

Core Principles

核心原则

Focus on "What" Not "How": Define deliverable outcomes, not implementation details. Specify constraints and success criteria, but leave implementation choices flexible.
Last Responsible Moment: Defer decisions until you have enough information to make them well, but not so late that they block progress. Make reversible decisions quickly; delay irreversible ones until necessary.
Risk-First Development: Address highest-risk technical challenges first. Build proof-of-concepts before full implementation. Ship working but imperfect solutions to validate core assumptions early.
Managed Deferral: Explicitly document what's being deferred and when it will be addressed. Distinguish between core value delivery and polish/optimization.
聚焦“做什么”而非“怎么做”：定义可交付的成果，而非实现细节。明确约束条件和成功标准，但保留实现方案的灵活性。
最后责任时刻：推迟决策直到掌握足够信息以做出合理判断，但不能晚到阻碍进度。快速做出可逆决策；必要时再推迟不可逆决策。
风险优先开发：优先处理最高风险的技术挑战。在全面实现前先构建概念验证。交付可用但不完美的解决方案，尽早验证核心假设。
可控延迟：明确记录延迟处理的内容及处理时间。区分核心价值交付与完善/优化工作。

Progress Tracking with TodoWrite

借助TodoWrite跟踪进度

Use TodoWrite to track planning progress through the four phases:
  1. At start: Create todos for each phase:
    ☐ Phase 1: Requirements & Risk Analysis
☐ Phase 2: Milestone Planning
☐ Phase 3: Implementation Strategy
☐ Phase 4: Execution Framework
  2. During planning: Mark phases in_progress → completed as you work through them. Add sub-todos for key deliverables:
    ☐ 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. For complex projects: Track clarifying questions and their resolutions as todos - prevents proceeding with incomplete information
使用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. 针对复杂项目：将澄清问题及其解决方案作为待办事项跟踪——避免在信息不全的情况下推进

Decision Timing Framework

决策时机框架

Decide Early (Requirements Phase):
  • User problems being solved
  • Success criteria and measurement
  • Hard constraints (security, compliance, performance SLAs)
  • Critical integrations and dependencies
  • Technology choices that affect architecture
Defer to Implementation (Execution Phase):
  • Specific algorithms or data structures
  • Internal API design details
  • Code organization patterns
  • Library choices (when multiple options work)
  • Performance optimizations (until proven necessary)
  • UI/UX details (until user testing)
Why: Early decisions should enable work without locking in details. Implementation decisions become clearer with hands-on experience and often reveal better alternatives than upfront planning suggests.
尽早决策（需求阶段）：
  • 要解决的用户问题
  • 成功标准与衡量方式
  • 硬性约束（安全、合规、性能SLA）
  • 关键集成与依赖项
  • 影响架构的技术选型
推迟至实施阶段决策（执行阶段）：
  • 特定算法或数据结构
  • 内部API设计细节
  • 代码组织模式
  • 库的选择（当多个选项都可行时）
  • 性能优化（直到被证明有必要时）
  • UI/UX细节（直到用户测试阶段）
原因：早期决策应推动工作开展，而非锁定细节。实施阶段的决策会随着实践经验变得更清晰，通常能比前期规划找到更好的替代方案。

Agent Guidelines

Agent指南

Seek Clarity Before Proceeding: Never assume unclear requirements, technical constraints, or business priorities. Only proceed when you have 80%+ confidence on critical aspects. Ask specific questions about:
  • User problems being solved (not just features requested)
  • Success criteria and measurement approaches
  • Technical constraints and existing system dependencies
  • Team capabilities and technology preferences
  • Timeline constraints and priority trade-offs
  • Performance and scalability requirements
推进前先明确信息：永远不要假设模糊的需求、技术约束或业务优先级。只有在关键方面拥有80%以上的信心时再推进。针对以下内容提出具体问题：
  • 要解决的用户问题（不只是请求的功能）
  • 成功标准与衡量方法
  • 技术约束与现有系统依赖
  • 团队能力与技术偏好
  • 时间线约束与优先级权衡
  • 性能与可扩展性要求

Phase 1: Requirements & Risk Analysis

阶段1：需求与风险分析

Prerequisites Check

前提检查

Verify:
  • What user problems are being solved?
  • Who are the primary users and their workflows?
  • How will success be measured?
  • What are the technical and business constraints?
确认：
  • 要解决的用户问题是什么？
  • 主要用户是谁以及他们的工作流程？
  • 如何衡量成功？
  • 技术与业务约束有哪些？

Extract Core Requirements

提取核心需求

  1. Identify fundamental user problems being solved
  2. Map primary user journeys (focus on 2-3 critical paths)
  3. Define project success metrics
  1. 识别要解决的核心用户问题
  2. 梳理主要用户旅程（聚焦2-3条关键路径）
  3. 定义项目成功指标

Identify Technical Risks

识别技术风险

  1. High-Impact Risks: Technical unknowns that could invalidate the approach
  2. Integration Risks: External system dependencies and compatibility concerns
  3. Performance Risks: Scalability bottlenecks and algorithmic challenges
  4. Architecture Risks: Fundamental design decisions with broad implications
  1. 高影响风险：可能使方案失效的技术未知项
  2. 集成风险：外部系统依赖与兼容性问题
  3. 性能风险：可扩展性瓶颈与算法挑战
  4. 架构风险：具有广泛影响的基础设计决策

Risk Prioritization Matrix

风险优先级矩阵

  • Critical + Unknown: Must be addressed in Milestone 1 with proof-of-concepts
  • Critical + Known: Address in early milestones with established patterns
  • Non-Critical: Defer to later milestones or eliminate
  • 关键+未知：必须在里程碑1中通过概念验证解决
  • 关键+已知：在早期里程碑中采用成熟模式解决
  • 非关键：推迟至后续里程碑或取消

Phase 2: Milestone Planning

阶段2：里程碑规划

Prerequisites Check

前提检查

Verify:
  • Priority order of technical risks identified in Phase 1
  • Team capacity and available timeline
  • Dependencies between different components
  • Definition of "working functionality" for this project
确认：
  • 阶段1中识别的技术风险优先级顺序
  • 团队能力与可用时间线
  • 不同组件之间的依赖关系
  • 本项目“可用功能”的定义

Milestone Structure

里程碑结构

  • Timeline: 4-8 week cycles based on project complexity
  • Deliverable: Each milestone must produce working, testable functionality
  • Risk Focus: Sequence milestones to tackle highest-risk items first
  • 时间线：根据项目复杂度设置4-8周的周期
  • 可交付成果：每个里程碑必须产出可运行、可测试的功能
  • 风险聚焦：按优先级排序里程碑，优先处理最高风险项

For Each Milestone, Define:

每个里程碑需定义：

Goal: One-sentence description of milestone outcome
Core Tasks: 4-6 main implementation tasks following Last Responsible Moment principle:
  • Define clear outcomes and constraints
  • Identify dependencies and integration points
  • Provide context and considerations (not step-by-step instructions)
  • Leave implementation details flexible
  • Flag questions to resolve during execution
Success Criteria:
  • Minimum Viable Success (must achieve for milestone completion)
  • Complete Success (ideal outcome including polish)
Risk Mitigation: Specific unknowns to be resolved in this milestone
Deferred Items: What's intentionally left out and target milestone for inclusion
目标：用一句话描述里程碑成果
核心任务：遵循最后责任时刻原则，设置4-6项主要实施任务：
  • 明确成果与约束条件
  • 识别依赖项与集成点
  • 提供背景信息与注意事项（而非分步指令）
  • 保留实现细节的灵活性
  • 标记执行过程中需要解决的问题
成功标准：
  • 最低可行成功（里程碑完成必须达到的标准）
  • 完全成功（包括完善工作的理想成果）
风险缓解：本里程碑中需解决的特定未知项
延迟项：有意排除的内容及其计划纳入的目标里程碑

Task Breakdown Guidelines

任务拆解指南

When breaking down tasks, provide guidance not prescription:
✓ Good Task Definition (outcome-focused):
  • Goal: "Enable users to authenticate securely"
  • Constraints: "Must integrate with existing session middleware; <100ms response time"
  • Guidance: "Consider session vs. token auth; review existing patterns in src/middleware/"
  • Validation: "Users can log in, sessions persist, tests pass"
✗ Poor Task Definition (overly prescriptive):
  • Step 1: "Create file auth.js with bcrypt import"
  • Step 2: "Write hashPassword function using bcrypt.hash with 10 rounds"
  • Step 3: "Create Express middleware checking req.session.userId"
Why: Good definitions let the implementer choose the best approach based on what they learn. Poor definitions lock in choices before understanding the context, often leading to rework.
拆解任务时，提供指导而非指令：
✓ 良好的任务定义（聚焦成果）：
  • 目标：“使用户能够安全认证”
  • 约束：“必须与现有会话中间件集成；响应时间<100ms”
  • 指导：“考虑会话认证vs令牌认证；参考src/middleware/中的现有模式”
  • 验证：“用户可以登录，会话持久化，测试通过”
✗ 糟糕的任务定义（过度指令化）：
  • 步骤1：“创建包含bcrypt导入的auth.js文件”
  • 步骤2：“使用bcrypt.hash（10轮）编写hashPassword函数”
  • 步骤3：“创建检查req.session.userId的Express中间件”
原因：良好的定义允许实施者根据所学选择最佳方案。糟糕的定义会在了解上下文前锁定选择，通常导致返工。

Example Milestone Definition

里程碑定义示例

Goal: Validate user authentication and basic data retrieval from external API
Core Tasks:
  1. Implement OAuth flow with provider
  2. Create user session management
  3. Build API client with error handling
  4. Add basic user profile display
Success Criteria:
  • Minimum: Users can log in and see their profile data
  • Complete: Include profile editing and session persistence
Risk Mitigation: Confirm API rate limits and response time under load
Deferred: Advanced profile features, password reset flow (Milestone 3)
目标：验证用户认证及从外部API检索基础数据的功能
核心任务：
  1. 实现与服务商的OAuth流程
  2. 创建用户会话管理功能
  3. 构建带错误处理的API客户端
  4. 添加基础用户资料展示功能
成功标准：
  • 最低标准：用户可以登录并查看其资料数据
  • 完全标准：包含资料编辑与会话持久化功能
风险缓解：确认API的速率限制及负载下的响应时间
延迟项：高级资料功能、密码重置流程（计划纳入里程碑3）

Phase 3: Implementation Strategy

阶段3：实施策略

Development Approach

开发方法

  • Prototype First: Build throwaway versions to test risky assumptions
  • Core Before Polish: Implement functional features before UI refinements
  • Integration Early: Test external system connections in first milestone
  • Measure Continuously: Track performance and user metrics from day one
  • 先做原型：构建一次性版本以测试高风险假设
  • 先核心后完善：在UI优化前先实现功能特性
  • 尽早集成：在第一个里程碑中测试外部系统连接
  • 持续衡量：从第一天开始跟踪性能与用户指标

Technology Selection Criteria

技术选型标准

  1. Team Expertise: Prefer technologies your team knows well
  2. Proven Reliability: Choose mature, battle-tested options for core systems
  3. Integration Capability: Ensure compatibility with existing tools/systems
  4. Scalability Path: Technology should support anticipated growth
  1. 团队专业能力：优先选择团队熟悉的技术
  2. 成熟可靠性：核心系统选择成熟、经实战检验的方案
  3. 集成能力：确保与现有工具/系统兼容
  4. 可扩展性路径：技术需支持预期的增长需求

Quality Gates

质量门

  • All code must have basic test coverage
  • Performance benchmarks must be met for core user journeys
  • Security review required for authentication and data handling
  • Accessibility standards met for user-facing features
  • 所有代码必须具备基础测试覆盖率
  • 核心用户旅程必须满足性能基准
  • 认证与数据处理需经过安全审查
  • 面向用户的功能需符合可访问性标准

Phase 4: Execution Framework

阶段4：执行框架

Sprint Planning

迭代规划

  1. Risk Assessment: Identify unknowns in upcoming work
  2. Exploration Time: Reserve 20-30% of sprint for prototyping/learning
  3. Definition of Done: Must include working functionality, not just completed code
  4. Continuous Validation: Regular stakeholder feedback on core user journeys
  1. 风险评估：识别后续工作中的未知项
  2. 探索时间：预留20-30%的迭代时间用于原型开发/学习
  3. 完成定义：必须包含可运行功能，而非仅完成代码
  4. 持续验证：定期收集利益相关者对核心用户旅程的反馈

Deferral Management

延迟项管理

  • Regular Review: Evaluate deferred items each milestone for continued relevance
  • Categories: Technical debt, UX polish, edge cases, performance optimization, advanced features
  • Scheduling: Plan deferred items into appropriate future milestones
  • Elimination: Some deferred items may become unnecessary
  • 定期回顾：每个里程碑评估延迟项的持续相关性
  • 分类：技术债务、UX完善、边缘案例、性能优化、高级功能
  • 排期：将延迟项规划至合适的未来里程碑中
  • 取消：部分延迟项可能变得不必要

Documentation Requirements

文档要求

  • Technical specification focusing on deliverable outcomes
  • Risk register with mitigation plans
  • Deferred items registry with target scheduling
  • Architecture decision records for major choices
  • 聚焦可交付成果的技术规格说明
  • 包含缓解计划的风险登记册
  • 包含目标排期的延迟项登记册
  • 重大决策的架构决策记录

Decision Framework for Agents

Agent决策框架

IF project has unknown technical feasibility → Schedule proof-of-concept in Milestone 1 IF project requires external integrations → Test minimal integration in first milestone IF project has performance requirements → Establish benchmarks and test core algorithms early IF team lacks expertise in chosen technology → Include learning/exploration time in early milestones IF project has tight deadlines → Focus on minimum viable success criteria and defer polish IF project is greenfield → Spend extra time on architecture decisions and foundational setup IF project is enhancement → Focus on integration points and backward compatibility
如果项目存在技术可行性未知项 → 在里程碑1中安排概念验证 如果项目需要外部集成 → 在第一个里程碑中测试最小集成 如果项目有性能要求 → 尽早建立基准并测试核心算法 如果团队对所选技术缺乏专业能力 → 在早期里程碑中纳入学习/探索时间 如果项目截止日期紧张 → 聚焦最低可行成功标准，推迟完善工作 如果项目是全新项目 → 投入额外时间进行架构决策与基础设置 如果项目是功能增强 → 聚焦集成点与向后兼容性

When Unclear - Ask These Questions

信息模糊时——提出这些问题

WHEN requirements are vague → "What specific user problem does this solve? How will we measure success?" WHEN technical scope is undefined → "What are the must-have vs. nice-to-have technical capabilities?" WHEN timeline is unrealistic → "What are the non-negotiable deadlines and what flexibility exists?" WHEN team capabilities are unknown → "What technologies does the team have experience with? What are the skill gaps?" WHEN integration points are unclear → "What existing systems must this connect to? What are the data formats and API constraints?" WHEN performance needs are unspecified → "What are the expected user loads and response time requirements?" WHEN success criteria are missing → "How will we know this milestone is complete and successful?"
当需求模糊时 → “这解决的是哪些具体用户问题？我们如何衡量成功？” 当技术范围未定义时 → “哪些是必备的技术能力，哪些是锦上添花的？” 当时间线不切实际时 → “哪些是不可协商的截止日期，存在哪些灵活性？” 当团队能力未知时 → “团队具备哪些技术经验？存在哪些技能差距？” 当集成点不明确时 → “必须与哪些现有系统连接？数据格式与API约束是什么？” 当性能需求未明确时 → “预期用户负载与响应时间要求是什么？” 当缺失成功标准时 → “我们如何判断这个里程碑已完成且成功？”

Common Pitfalls to Avoid

需避免的常见陷阱

  • Making assumptions instead of asking clarifying questions when requirements are unclear
  • Proceeding with incomplete information rather than requesting necessary details
  • Creating overly prescriptive task definitions with step-by-step instructions instead of outcome-focused guidance
  • Making implementation decisions too early when they could be deferred to execution
  • Spending time on low-risk features while deferring critical unknowns
  • Over-engineering solutions before validating core assumptions
  • Planning implementation details instead of focusing on deliverable outcomes
  • Guessing at user needs instead of understanding specific problems being solved
  • Failing to document deferral decisions and rationale
  • Optimizing prematurely instead of proving core functionality first
  • Locking in technology choices before understanding the full context
  • 需求模糊时做出假设而非提出澄清问题
  • 在信息不全的情况下推进工作，而非请求必要细节
  • 创建过度指令化的任务定义（分步指令）而非聚焦成果的指导
  • 过早做出实施决策，而这些决策本可推迟至执行阶段
  • 花费时间在低风险功能上，却推迟处理关键未知项
  • 在验证核心假设前过度设计解决方案
  • 规划实现细节而非聚焦可交付成果
  • 猜测用户需求而非理解要解决的具体问题
  • 未记录延迟决策及其理由
  • 在证明核心功能前过早优化
  • 在了解完整上下文前锁定技术选型