tech-design

写好一份技术设计 / 方案文档的方法论。一个给 AI agent 用的 skill。

它解决什么问题

技术方案文档常见的三个毛病：

• 套模板：从头到尾把所有 section 填一遍，看着齐全其实是填空作业；
• 伪代码流畅性错觉：核心设计用伪代码糊弄，看着顺滑其实没想清；
• 静态快照：文档写完即冻结，方案一变整篇作废。

tech-design 把"写一份好的技术方案"拆成三步流水线，各治一个毛病。

三步流水线

1. 先讨论（references/discussion-framework.md）——动手写之前，逐项过 触发 / 数据 / 核心逻辑 / 依赖 / 结果 / 埋点 / 开关降级 / 改造点 / 工期 / PRD 对照，把结论讨论清楚再"翻译"成文档。跳过讨论直接写，等于把没想清的东西固化成文档。
2. 选 section（references/skeleton.md）——这是点菜菜单不是填空表单。按需求类型选基础/豪华套餐做底，再按场景加点菜。挑这次真需要的，其余不写。
3. 写得活（references/livedoc.md）——活 SSOT 五纪律（当前真相置顶 / 废弃沉底 / 假设-事实分区 / 证据链嵌入 / 人类导航）+ CR 前移（核心设计写评审级真代码而非伪代码，落 src 后降权为指针）。

何时用

• 要写技术方案 / 设计文档 / 评审文档 / 落地方案时；
• 探索一个点子、想把"怎么实现"想清楚时（此时未必有正式项目）；
• 在 standard-cycle 项目里，designs/ 槽位的方案文档委托本 skill 来写好。

tech-design 独立可用——它不依赖 standard-cycle。写设计文档常发生在探索期、standard-cycle 尚未引入时，所以它需要能被"写技术方案"独立唤起。

文件结构

文件	内容
SKILL.md	三步流水线的编排（agent 执行入口）
references/discussion-framework.md	第 1 步：动手前的讨论框架（10 段逐项过）
references/skeleton.md	第 2 步：section 骨架（基础/豪华套餐 + 加点菜）
references/livedoc.md	第 3 步：把每节写成活 SSOT + CR 前移

安装

自包含，无外部依赖。

方式一：用 skill 工厂（推荐）

如果你用 skill-factory 统一管理 skill：

# 1. 把本仓库 clone 进你的 skill 工厂
# 2. 在 publish.map 注册（all = 分发到所有 agent）
echo "tech-design=tech-design|all" >> publish.map
# 3. 安装
./install.sh tech-design

install.sh 会给每个 agent 的 skills 目录建软链，指回这份唯一源码——改一处，所有 agent 立刻生效。

方式二：手动软链

不用 skill 工厂的话，直接软链到你的 agent 的 skills 目录：

ln -s /path/to/tech-design ~/.claude/skills/tech-design

不同 agent 的 skills 目录不同（Claude Code 是 ~/.claude/skills/，QoderWork 是 ~/.qoderwork/skills/，Cursor 是 ~/.cursor/skills/，等等）。

配套

• standard-cycle：文档驱动的 AI 协作项目管理。tech-design 填充它的 designs/ 槽位。

成熟度

v0.1，基于 2 个实战案例提炼（都是"新增"类）。缺性能优化 / 链路重构 / 数据迁移类案例，随案例迭代。

License

MIT