{"id":"fe633c30-a470-4236-93cf-11cac822f9ed","shortId":"Azd4DZ","kind":"skill","title":"writing-plans","tagline":"当你有规格说明或需求用于多步骤任务时使用，在动手写代码之前","description":"# 编写计划\n\n## 概述\n\n编写全面的实现计划，假设工程师对我们的代码库零上下文，且品味存疑。记录他们需要知道的一切：每个任务要修改哪些文件、代码、测试、可能需要查阅的文档、如何测试。将整个计划拆成小步骤任务。DRY。YAGNI。TDD。频繁 commit。\n\n假设他们是有经验的开发者，但对我们的工具链和问题领域几乎一无所知。假设他们不太擅长测试设计。\n\n**开始时宣布：** \"我正在使用 writing-plans 技能创建实现计划。\"\n\n**上下文：** 此技能应在专用 worktree 中运行（由 brainstorming 技能创建）。\n\n**计划保存位置：** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`\n- （用户对计划位置的偏好优先于此默认值）\n\n## 范围检查\n\n如果规格涵盖了多个独立子系统，它应该在头脑风暴阶段就被拆分为子项目规格。如果没有，建议将其拆分为独立的计划——每个子系统一个。每个计划应该能独立产出可工作、可测试的软件。\n\n## 文件结构\n\n在定义任务之前，先列出将要创建或修改的文件以及每个文件的职责。这是锁定分解决策的地方。\n\n- 设计边界清晰、接口定义良好的单元。每个文件应有一个明确的职责。\n- 你对能一次放入上下文的代码推理得最好，文件越专注你的编辑越可靠。优先选择小而专注的文件，而非承担过多功能的大文件。\n- 一起变更的文件应放在一起。按职责拆分，而非按技术层级拆分。\n- 在现有代码库中，遵循已有模式。如果代码库使用大文件，不要单方面重构——但如果你正在修改的文件已经变得难以管理，在计划中包含拆分是合理的。\n\n此结构决定了任务分解。每个任务应产出独立的、有意义的变更。\n\n## 小步骤任务粒度\n\n**每步是一个操作（2-5 分钟）：**\n- \"编写失败的测试\" - 一步\n- \"运行它确认失败\" - 一步\n- \"实现最少代码让测试通过\" - 一步\n- \"运行测试确认通过\" - 一步\n- \"Commit\" - 一步\n\n## 计划文档头部\n\n**每个计划必须以此头部开始：**\n\n```markdown\n# [功能名称] 实现计划\n\n> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。\n\n**目标：** [一句话描述要构建什么]\n\n**架构：** [2-3 句话描述方案]\n\n**技术栈：** [关键技术/库]\n\n---\n```\n\n## 任务结构\n\n````markdown\n### 任务 N：[组件名称]\n\n**文件：**\n- 创建：`exact/path/to/file.py`\n- 修改：`exact/path/to/existing.py:123-145`\n- 测试：`tests/exact/path/to/test.py`\n\n- [ ] **步骤 1：编写失败的测试**\n\n```python\ndef test_specific_behavior():\n    result = function(input)\n    assert result == expected\n```\n\n- [ ] **步骤 2：运行测试验证失败**\n\n运行：`pytest tests/path/test.py::test_name -v`\n预期：FAIL，报错 \"function not defined\"\n\n- [ ] **步骤 3：编写最少实现代码**\n\n```python\ndef function(input):\n    return expected\n```\n\n- [ ] **步骤 4：运行测试验证通过**\n\n运行：`pytest tests/path/test.py::test_name -v`\n预期：PASS\n\n- [ ] **步骤 5：Commit**\n\n```bash\ngit add tests/path/test.py src/path/file.py\ngit commit -m \"feat: add specific feature\"\n```\n````\n\n## 禁止占位符\n\n每个步骤都必须包含工程师需要的实际内容。以下是**计划缺陷**——绝不要写出来：\n- \"待定\"、\"TODO\"、\"后续实现\"、\"补充细节\"\n- \"添加适当的错误处理\" / \"添加验证\" / \"处理边界情况\"\n- \"为上述代码编写测试\"（没有实际测试代码）\n- \"类似任务 N\"（重复代码——工程师可能不按顺序阅读任务）\n- 只描述做什么而不展示怎么做的步骤（代码步骤必须有代码块）\n- 引用了未在任何任务中定义的类型、函数或方法\n\n## 注意事项\n- 始终使用精确的文件路径\n- 每个步骤都包含完整代码——如果步骤涉及代码变更，就展示代码\n- 精确的命令和预期输出\n- DRY、YAGNI、TDD、频繁 commit\n\n## 自检\n\n编写完整计划后，以全新视角审视规格并对照检查计划。这是你自己执行的检查清单——不是子代理调度。\n\n**1. 规格覆盖度：** 浏览规格中的每个章节/需求。你能指出实现它的任务吗？列出所有遗漏。\n\n**2. 占位符扫描：** 搜索计划中的红旗——上方\"禁止占位符\"章节中的任何模式。修复它们。\n\n**3. 类型一致性：** 后续任务中使用的类型、方法签名和属性名是否与前面任务中定义的一致？任务 3 中叫 `clearLayers()` 但任务 7 中叫 `clearFullLayers()` 就是 bug。\n\n如果发现问题，直接内联修复。无需重新审查——修好继续推进。如果发现规格中的需求没有对应任务，就添加任务。\n\n## 执行交接\n\n保存计划后，提供执行选项：\n\n**\"计划已完成并保存到 `docs/superpowers/plans/<filename>.md`。两种执行方式：**\n\n**1. 子代理驱动（推荐）** - 每个任务调度一个新的子代理，任务间进行审查，快速迭代\n\n**2. 内联执行** - 在当前会话中使用 executing-plans 执行任务，批量执行并设有检查点\n\n**选哪种方式？\"**\n\n**如果选择子代理驱动：**\n- **必需子技能：** 使用 superpowers:subagent-driven-development\n- 每个任务一个新子代理 + 两阶段审查\n\n**如果选择内联执行：**\n- **必需子技能：** 使用 superpowers:executing-plans\n- 批量执行并设有检查点供审查","tags":["writing","plans","superpowers","jnmetacode","agent-skills","agentic-coding","ai-coding","chinese","claude-code","code-review","cursor","gemini-cli"],"capabilities":["skill","source-jnmetacode","skill-writing-plans","topic-agent-skills","topic-agentic-coding","topic-ai-coding","topic-chinese","topic-claude-code","topic-code-review","topic-cursor","topic-gemini-cli","topic-kiro","topic-mcp","topic-npm-package","topic-prompt-engineering"],"categories":["superpowers-zh"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/jnMetaCode/superpowers-zh/writing-plans","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add jnMetaCode/superpowers-zh","source_repo":"https://github.com/jnMetaCode/superpowers-zh","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 1850 github stars · SKILL.md body (2,814 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-02T18:52:41.268Z","embedding":null,"createdAt":"2026-04-18T21:56:05.060Z","updatedAt":"2026-05-02T18:52:41.268Z","lastSeenAt":"2026-05-02T18:52:41.268Z","tsv":"'-145':133 '-3':117 '-5':77 '1':137,238,278 '123':132 '2':76,116,151,244,284 '3':166,251,256 '4':175 '5':186 '7':260 'add':190,197 'ai':95 'assert':147 'bash':188 'behavior':143 'brainstorm':37 'bug':264 'clearfulllay':262 'clearlay':258 'commit':22,87,187,194,232 'def':140,169 'defin':164 'develop':103,300 'docs/superpowers/plans':275 'docs/superpowers/plans/yyyy-mm-dd-':40 'dri':18,228 'driven':102,299 'exact/path/to/existing.py':131 'exact/path/to/file.py':129 'execut':108,288,308 'executing-plan':107,287,307 'expect':149,173 'fail':160 'feat':196 'featur':199 'function':145,162,170 'git':189,193 'input':146,171 'm':195 'markdown':91,123 'md':41,276 'n':125,215 'name':157,181 'pass':184 'plan':3,30,109,289,309 'pytest':154,178 'python':139,168 'result':144,148 'return':172 'skill' 'skill-writing-plans' 'source-jnmetacode' 'specif':142,198 'src/path/file.py':192 'subag':101,298 'subagent-driven-develop':100,297 'superpow':99,106,296,306 'tdd':20,230 'test':141,156,180 'tests/exact/path/to/test.py':135 'tests/path/test.py':155,179,191 'todo':206 'topic-agent-skills' 'topic-agentic-coding' 'topic-ai-coding' 'topic-chinese' 'topic-claude-code' 'topic-code-review' 'topic-cursor' 'topic-gemini-cli' 'topic-kiro' 'topic-mcp' 'topic-npm-package' 'topic-prompt-engineering' 'v':158,182 'worktre':34 'write':2,29 'writing-plan':1,28 'yagni':19,229 '一句话描述要构建什么':114 '一步':80,82,84,86,88 '一起变更的文件应放在一起':62 '上下文':32 '上方':247 '不是子代理调度':237 '不要单方面重构':68 '且品味存疑':10 '两种执行方式':277 '两阶段审查':302 '中叫':257,261 '中运行':35 '为上述代码编写测试':212 '代理的工作者':96 '代码':13 '代码步骤必须有代码块':219 '以下是':202 '以全新视角审视规格并对照检查计划':235 '任务':124,255 '任务结构':122 '任务间进行审查':282 '优先选择小而专注的文件':60 '但任务':259 '但如果你正在修改的文件已经变得难以管理':69 '但对我们的工具链和问题领域几乎一无所知':24 '你对能一次放入上下文的代码推理得最好':58 '你能指出实现它的任务吗':242 '使用':98,295,305 '保存计划后':272 '修复它们':250 '修好继续推进':268 '修改':130 '假设他们不太擅长测试设计':25 '假设他们是有经验的开发者':23 '假设工程师对我们的代码库零上下文':9 '先列出将要创建或修改的文件以及每个文件的职责':53 '关键技术':120 '内联执行':285 '函数或方法':221 '分钟':78 '列出所有遗漏':243 '创建':128 '功能名称':92 '占位符扫描':245 '句话描述方案':118 '只描述做什么而不展示怎么做的步骤':218 '可测试的软件':50 '可能需要查阅的文档':15 '后续任务中使用的类型':253 '后续实现':207 '在动手写代码之前':5 '在定义任务之前':52 '在当前会话中使用':286 '在现有代码库中':65 '在计划中包含拆分是合理的':70 '处理边界情况':211 '如何测试':16 '如果代码库使用大文件':67 '如果发现规格中的需求没有对应任务':269 '如果发现问题':265 '如果步骤涉及代码变更':225 '如果没有':46 '如果规格涵盖了多个独立子系统':44 '如果选择内联执行':303 '如果选择子代理驱动':293 '始终使用精确的文件路径':223 '子代理驱动':279 '它应该在头脑风暴阶段就被拆分为子项目规格':45 '实现最少代码让测试通过':83 '实现计划':93 '将整个计划拆成小步骤任务':17 '小步骤任务粒度':74 '就展示代码':226 '就是':263 '就添加任务':270 '工程师可能不按顺序阅读任务':217 '库':121 '建议将其拆分为独立的计划':47 '开始时宣布':26 '引用了未在任何任务中定义的类型':220 '当你有规格说明或需求用于多步骤任务时使用':4 '待定':205 '必需子技能':97,294,304 '快速迭代':283 '我正在使用':27 '或':105 '执行交接':271 '执行任务':290 '批量执行并设有检查点':291 '批量执行并设有检查点供审查':310 '技术栈':119 '技能创建':38 '技能创建实现计划':31 '报错':161 '按职责拆分':63 '接口定义良好的单元':56 '推荐':104,280 '提供执行选项':273 '搜索计划中的红旗':246 '文件':127 '文件结构':51 '文件越专注你的编辑越可靠':59 '方法签名和属性名是否与前面任务中定义的一致':254 '无需重新审查':267 '有意义的变更':73 '架构':115 '概述':7 '此技能应在专用':33 '此结构决定了任务分解':71 '步骤':136,150,165,174,185 '步骤使用复选框':111 '每个任务一个新子代理':301 '每个任务应产出独立的':72 '每个任务要修改哪些文件':12 '每个任务调度一个新的子代理':281 '每个子系统一个':48 '每个文件应有一个明确的职责':57 '每个步骤都包含完整代码':224 '每个步骤都必须包含工程师需要的实际内容':201 '每个计划应该能独立产出可工作':49 '每个计划必须以此头部开始':90 '每步是一个操作':75 '没有实际测试代码':213 '注意事项':222 '测试':14,134 '浏览规格中的每个章节':240 '添加适当的错误处理':209 '添加验证':210 '用户对计划位置的偏好优先于此默认值':42 '由':36 '目标':113 '直接内联修复':266 '禁止占位符':200,248 '章节中的任何模式':249 '类似任务':214 '类型一致性':252 '精确的命令和预期输出':227 '组件名称':126 '绝不要写出来':204 '编写全面的实现计划':8 '编写失败的测试':79,138 '编写完整计划后':234 '编写最少实现代码':167 '编写计划':6 '而非承担过多功能的大文件':61 '而非按技术层级拆分':64 '自检':233 '范围检查':43 '补充细节':208 '规格覆盖度':239 '计划保存位置':39 '计划已完成并保存到':274 '计划文档头部':89 '计划缺陷':203 '记录他们需要知道的一切':11 '设计边界清晰':55 '语法来跟踪进度':112 '运行':153,177 '运行它确认失败':81 '运行测试确认通过':85 '运行测试验证失败':152 '运行测试验证通过':176 '这是你自己执行的检查清单':236 '这是锁定分解决策的地方':54 '选哪种方式':292 '逐任务实现此计划':110 '遵循已有模式':66 '重复代码':216 '需求':241 '面向':94 '预期':159,183 '频繁':21,231","prices":[{"id":"6a1c8873-fe6b-44fa-80a6-a5371ebdce4d","listingId":"fe633c30-a470-4236-93cf-11cac822f9ed","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"jnMetaCode","category":"superpowers-zh","install_from":"skills.sh"},"createdAt":"2026-04-18T21:56:05.060Z"}],"sources":[{"listingId":"fe633c30-a470-4236-93cf-11cac822f9ed","source":"github","sourceId":"jnMetaCode/superpowers-zh/writing-plans","sourceUrl":"https://github.com/jnMetaCode/superpowers-zh/tree/main/skills/writing-plans","isPrimary":false,"firstSeenAt":"2026-04-18T21:56:05.060Z","lastSeenAt":"2026-05-02T18:52:41.268Z"}],"details":{"listingId":"fe633c30-a470-4236-93cf-11cac822f9ed","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"jnMetaCode","slug":"writing-plans","github":{"repo":"jnMetaCode/superpowers-zh","stars":1850,"topics":["agent-skills","agentic-coding","ai-coding","chinese","claude-code","code-review","cursor","gemini-cli","kiro","mcp","npm-package","prompt-engineering","skills","superpowers","tdd","trae"],"license":"mit","html_url":"https://github.com/jnMetaCode/superpowers-zh","pushed_at":"2026-04-28T15:32:18Z","description":"🦸 AI 编程超能力 · 中文增强版 — superpowers（116k+ ⭐）完整汉化 + 6 个中国原创 skills，让 Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI 等 16 款 AI 编程工具真正会干活","skill_md_sha":"e51c0e8dc08fd023fc83795b4766a17956decb90","skill_md_path":"skills/writing-plans/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/jnMetaCode/superpowers-zh/tree/main/skills/writing-plans"},"layout":"multi","source":"github","category":"superpowers-zh","frontmatter":{"name":"writing-plans","description":"当你有规格说明或需求用于多步骤任务时使用，在动手写代码之前"},"skills_sh_url":"https://skills.sh/jnMetaCode/superpowers-zh/writing-plans"},"updatedAt":"2026-05-02T18:52:41.268Z"}}