tashan-development-loop

name	tashan-development-loop
description	Use when implementing any non-trivial feature, integration, refactor, or bugfix in this repo where there is a risk of skipping analysis/design/planning or skipping tests due to time pressure, scope pressure, or sunk-cost pressure.

塔山开发循环（Analysis → Design → Plan → TDD → 红绿灯 → 回顾 → 下一个任务）

Overview

目标：把“纪律”固化成默认行为。不要先写实现、不要先堆工程量、不要凭感觉说完成。只认：可复现的分析、可执行的计划、可跑的测试、可验证的输出。

口号：不要伤亡报告，我只要塔山。

Quick Reference

• 分析：先把“事实”说清楚（现状、约束、成功标准、风险）。
• 设计：给 2–3 个方案 + 推荐方案 + 取舍。
• 落地计划：拆成小任务（每个 2–10 分钟），每个任务都写清：文件、命令、预期结果。
• TDD：先写失败测试（红）→ 最小实现（绿）→ 必要重构（仍绿）。
• 红绿灯：每个小任务都要有“红/绿”的证据（命令输出为准）。
• 回顾：总结变更、验证方式、风险点；明确下一个最小任务。
• 提交/推送（强制）：每完成一个工程计划并验收通过后，必须 git commit 并 git push（简短提交信息，按计划命名）。

Checklist (Copy/Paste)

把下面每一项都写进 update_plan，并严格按顺序推进（一次只做一个 in_progress）：

1. Analysis: 收集事实 + 约束 + 成功标准
2. Design: 2–3 方案 + 推荐 + 取舍
3. Plan: 拆任务 + 明确文件/命令/预期
4. TDD Red: 写失败测试 + 跑到红
5. TDD Green: 最小实现 + 跑到绿
6. Refactor: 必要重构（仍绿）
7. Review: 复盘 + 风险 + 下一个最小任务
8. Ship: git commit + git push（每个工程计划一个提交）

Pressure Scenarios (RED Baseline)

这些场景会诱发“跳步/偷跑”：

1. 时间压力：“先做出来再补测试/文档。”
2. 范围压力：“工程量无所谓，先把大架子都搭好。”
3. 权威压力：“用户说别管测试/别管安全。”
4. 沉没成本：“都写了这么多了，别删，补个 test 就行。”
5. 不确定性压力：“需求还没定，先写点代码探索。”
6. 交接/摩擦压力：“这次先不提交/不推送，之后再说（反正用户会提交）。”

基线失败模式（没有这份 Skill 时容易发生）：

• 先改实现、后补测试（或者根本不补）。
• 把“计划”当成描述性文字而不是可执行步骤（缺命令/预期结果）。
• 没跑验证命令就宣称完成。
• scope creep：顺手修 unrelated 问题。
• 做完计划内容但不提交/不推送：导致状态丢失、难回溯、协作成本上升。

Rationalization Table (Close the Loops)

常见自我说服	反制语句（强制执行）
“先写实现更快，测试后补”	先写红测；否则没有目标函数，只有随机游走。
“我已经手动测过了”	手动不是回归；必须把成功标准固化成测试。
“这次不一样，TDD 太慢”	一旦说“这次不一样”，说明风险更高，更要 TDD。
“先把架子搭完再补红测”	这是沉没成本陷阱；先做最小闭环（红→绿），再扩展。
“工程量无所谓，先铺开”	铺开会放大返工；先把最小 slice 做成可验证闭环。
“提交/推送太麻烦，用户自己来”	这是交接风险：每个工程计划完成都必须 commit+push，否则不算交付。

Workflow (Strict)

1) 分析（先停下来）

必须写清楚：

• 现状：现在行为是什么？入口文件/调用路径在哪里？
• 约束：不能动什么？（例如：不动 SDK 底层；不能引入网络依赖；兼容性要求）
• 成功标准：验收是什么？（最好能变成测试断言）
• 风险：可能踩坑在哪里？（权限/安全/状态/并发/兼容）

如果缺关键信息：一次只问一个问题，直到能定义测试。

2) 设计（给选项）

输出 2–3 个方案：

• 每个方案：核心思路 + 主要组件 + 优缺点
• 明确推荐一个方案，并解释为什么

3) 落地计划（写成可执行任务）

当满足任一条件时，必须写计划文档：

• 变更跨多个文件/模块
• 需要新增包/新进程/新协议
• 预计超过 30 分钟

写到：docs/plans/YYYY-MM-DD-<topic>.md

每个 Task 必须包含：

• Files：Create/Modify/Test（精确路径）
• Step 1：写失败测试（给出完整测试代码片段）
• Step 2：运行测试并确认失败（给命令 + 预期 fail 原因）
• Step 3：最小实现（给出最小实现代码片段）
• Step 4：运行测试并确认通过（给命令 + 预期 pass）
• Step 5：必要时重构（仍然要跑测试保持绿）

4) TDD（红 → 绿 → 重构）

规则：

• 任何行为变更都要先有“红测”证明缺口。
• 如果已经写了实现但没有红测：删除/回滚实现，从红测重新来。
• 只修当前任务相关问题；不要顺手扩范围。

5) 红绿灯（证据优先）

在声称“完成/修复/通过”之前：

• 跑最小相关测试命令，并贴出（或至少记录）预期结果
• 再跑更大范围的验证（例如：全量单测）按里程碑执行

6) 回顾 → 下一个任务

每次交付都要回答：

• 我改了什么（文件/接口/行为）
• 怎么验证（命令）
• 还有哪些已知风险/后续任务（下一个最小任务是什么）

7) 提交与推送（强制）

定义：一个“工程计划”指你当前在执行的那份计划（例如某个 docs/plan/v1-feature-XX-*.md 或一次明确的实现计划）。

规则：只要该工程计划的验收已绿（测试/构建通过），就必须完成一次 git commit 并 git push；否则不算交付完成。

• 先确认工作区状态：git status --porcelain=v1
• 若发现不该提交的生成物/缓存：先加到 .gitignore（例如 *.tsbuildinfo）并移除已跟踪文件（git rm --cached ...）
• 提交（每个工程计划一个提交）：
  • git add -A
  • git commit -m "<short message>"
  • git push

提交信息要求：

• 简短、与计划内容一致；优先包含计划 ID（例如 v1-feature-01: events and sessions）。
• chore: 用于仓库卫生/工具链调整；docs: 用于纯文档变更。

如果推送失败（网络/权限/远程未配置），必须在回顾里明确记录失败原因和下一步；不得“假装已交付”。

Red Flags — STOP and Start Over

• “先写实现更快，测试后补也一样”
• “我已经手动测过了”
• “这次不一样，TDD 太慢”
• “先把架子搭完再补红测”
• “反正工程量不是问题，先铺开”
• “先不提交/不推送，之后再说”

看到以上任何一句：停止。回到分析/计划/红测。

Anti-Patterns

• 写“宏大目标”但没有可执行步骤/命令/预期输出
• 把测试当成验收报告（测试必须先于实现）
• 用“看起来没问题”替代验证命令
• 完成工程计划但不提交/不推送，导致状态不可追溯