[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M71Q6PQJ5J2ZQ59G1R5SZTFR":3,"skill-same:01M71Q6PQJ5J2ZQ59G1R5SZTFR":69},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":22,"publishedAt":32,"linkOnly":33,"markdownContent":34,"markdownBody":35,"frontMatter":36,"refName":38,"commitSha":39,"skillDirectory":40,"forksCount":41,"repositoryHtmlUrl":42,"repositoryHomepageUrl":43,"ownerHtmlUrl":44,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":45,"install":46,"resources":58},"01M71Q6PQJ5J2ZQ59G1R5SZTFR","improve-codebase-architecture",null,"扫描代码库中的深化机会，生成可视化 HTML 报告，然后围绕你选中的候选项继续追问。","vinvcn\u002Fmattpocock-skills-zh-CN","vinvcn","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F120928190?v=4","01M71Q60C4V98DEXHGN2VXFSZB","01M71Q60D6PRAJHKQRY33ZNE59",5797,"MIT","https:\u002F\u002Fgithub.com\u002Fvinvcn\u002Fmattpocock-skills-zh-CN\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Fimprove-codebase-architecture\u002FSKILL.md",[17],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000009","前端开发","SCENARIO","使用场景",[23,24,25,26,27,28,29,30,31],"improve codebase architecture","architecture","improve","codebase","生成","html","可视化","true","报告","2026-11-10 13:02:02",false,"---\nname: improve-codebase-architecture\ndescription: 扫描代码库中的深化机会，生成可视化 HTML 报告，然后围绕你选中的候选项继续追问。\ndisable-model-invocation: true\n---\n\n# 改进代码库架构\n\n暴露 architectural friction，并提出 **deepening opportunities**：把 shallow modules 变成 deep modules 的 refactors。目标是 testability 和 AI-navigability。\n\n这个命令由项目的 domain model 提供信息，并建立在共享 design vocabulary 上：\n\n- 调用 Skill 工具并指定 `codebase-design`，获取 architecture vocabulary（**module**、**interface**、**depth**、**seam**、**adapter**、**leverage**、**locality**）及其 principles（deletion test、\"the interface is the test surface\"、\"one adapter = hypothetical seam, two = real\"）。每条建议都准确使用这些术语，不要漂移到 \"component\"、\"service\"、\"API\" 或 \"boundary\"。\n- `GLOSSARY.md` 中的 domain language 会为好的 seams 命名；`docs\u002Fadr\u002F` 中的 ADRs 记录这个命令不应重新争论的 decisions。\n\n## 流程\n\n### 1. 探索\n\n**先划定扫描范围：YAGNI。** 深化 module 的收益在于让未来修改更容易，因此要更关注最近仍在变化的 codebase 区域。开始探索前先决定去哪里看：\n\n- 如果用户点名了方向（module、subsystem 或 pain point），就按该方向探索，跳过下面的推断。\n- 否则，向前回看一段足够长的 commit history（`git log --oneline`），找出反复出现的 files 和 areas，让这些 hot spots 成为首要关注点。如果变更分散、没有明显 hot spot，再扩大范围。\n\n先读取项目 domain glossary（`GLOSSARY.md`）以及你将触碰区域的 ADRs。\n\n然后 spawn 一个使用全新 context window 的 sub-agent 来遍历 codebase。不要套死板 heuristics；自然探索，并记录你感到 friction 的地方：\n\n- 理解一个概念是否需要在许多小 modules 之间来回跳？\n- 哪些 modules 是 **shallow** 的，即 interface 几乎和 implementation 一样复杂？\n- 是否存在为了 testability 抽出的 pure functions，但真正 bugs 藏在它们如何被调用之处（没有 **locality**）？\n- 哪些 tightly-coupled modules 泄漏到了 seams 之外？\n- Codebase 的哪些部分未测试，或很难通过当前 interface 测试？\n\n对任何你怀疑 shallow 的东西应用 **deletion test**：删除它会让复杂度集中，还是只把复杂度移动到别处？\"yes, concentrates\" 才是你要的 signal。\n\n### 2. 用 HTML 报告呈现候选项\n\n把 self-contained HTML file 写到 OS temp directory，避免任何内容落进 repo。Temp dir 从 `$TMPDIR` 解析，fallback 到 `\u002Ftmp`（Windows 用 `%TEMP%`），写到 `\u003Ctmpdir>\u002Farchitecture-review-\u003Ctimestamp>.html`，让每次运行都有新文件。为用户打开它：Linux 用 `xdg-open \u003Cpath>`，macOS 用 `open \u003Cpath>`，Windows 用 `start \u003Cpath>`，并告诉用户 absolute path。\n\nReport 使用 **Tailwind via CDN** 做 layout\u002Fstyling，用 **Mermaid via CDN** 做能可靠传达结构的 diagrams。Mermaid 和手写 CSS\u002FSVG visuals 可以混用：关系是 graph-shaped（call graphs、dependencies、sequences）时用 Mermaid；需要 editorial 表达（mass diagrams、cross-sections、collapse animations）时用手写 divs\u002FSVG。每个 candidate 都要有 **before\u002Fafter visualisation**。要视觉化。\n\n每个 candidate 渲染一张 card，包含：\n\n- **Files** - 涉及哪些 files\u002Fmodules\n- **Problem** - 当前 architecture 为什么造成 friction\n- **Solution** - 会改变什么，用平实的语言描述\n- **Benefits** - 用 locality 与 leverage 解释收益，以及 tests 如何改善\n- **Before \u002F After diagram** - side-by-side，自绘，说明 shallowness 与 deepening\n- **Recommendation strength** - `Strong`、`Worth exploring`、`Speculative` 之一，渲染为 badge\n\nReport 末尾包含**首选推荐区**：你会先处理哪个 candidate，以及为什么。\n\n**用 `GLOSSARY.md` vocabulary 表达 domain，用 `\u002Fcodebase-design` vocabulary 表达 architecture。** 如果 `GLOSSARY.md` 定义了 \"Order\"，就说 \"Order intake module\"，不要说 \"FooBarHandler\"，也不要说 \"Order service\"。\n\n**ADR conflicts**：如果 candidate 与现有 ADR 冲突，只有在 friction 真实到值得重新打开 ADR 时才提出。Card 中明确标记（例如 warning callout：_\"contradicts ADR-0007 - but worth reopening because...\"_）。不要列出 ADR 理论上禁止的每个 refactor。\n\n完整 HTML scaffold、diagram patterns 和 styling guidance 见 [HTML-REPORT.md](HTML-REPORT.md)。\n\n现在不要提出 interfaces。写完文件后问用户：\"Which of these would you like to explore?\"\n\n### 3. Grilling 循环\n\n用户选中 candidate 后，调用 Skill 工具并指定 `grilling`，与用户走完 decision tree：constraints、dependencies、deepened module 的形状、seam 后面放什么、哪些 tests 能保留。\n\nSide effects 随 decisions 成形而内联发生；调用 Skill 工具并指定 `domain-modeling`，让 domain model 保持最新：\n\n- **要用 `GLOSSARY.md` 中不存在的概念命名 deepened module？** 把 term 加入 `GLOSSARY.md`。若文件不存在，按需创建。\n- **对话中打磨了 fuzzy term？** 立即更新 `GLOSSARY.md`。\n- **用户以 load-bearing reason 拒绝了 candidate？** 提议写 ADR，表述为：_\"Want me to record this as an ADR so future architecture reviews don't re-suggest it?\"_ 只有当未来 explorer 确实需要该 reason 以避免再次提出同样建议时才提议；跳过临时原因（\"not worth it right now\"）和显而易见原因。\n- **想探索 deepened module 的 alternative interfaces？** 调用 Skill 工具并指定 `codebase-design`，并使用其中的 design-it-twice parallel sub-agent pattern。\n","# 改进代码库架构\n\n暴露 architectural friction，并提出 **deepening opportunities**：把 shallow modules 变成 deep modules 的 refactors。目标是 testability 和 AI-navigability。\n\n这个命令由项目的 domain model 提供信息，并建立在共享 design vocabulary 上：\n\n- 调用 Skill 工具并指定 `codebase-design`，获取 architecture vocabulary（**module**、**interface**、**depth**、**seam**、**adapter**、**leverage**、**locality**）及其 principles（deletion test、\"the interface is the test surface\"、\"one adapter = hypothetical seam, two = real\"）。每条建议都准确使用这些术语，不要漂移到 \"component\"、\"service\"、\"API\" 或 \"boundary\"。\n- `GLOSSARY.md` 中的 domain language 会为好的 seams 命名；`docs\u002Fadr\u002F` 中的 ADRs 记录这个命令不应重新争论的 decisions。\n\n## 流程\n\n### 1. 探索\n\n**先划定扫描范围：YAGNI。** 深化 module 的收益在于让未来修改更容易，因此要更关注最近仍在变化的 codebase 区域。开始探索前先决定去哪里看：\n\n- 如果用户点名了方向（module、subsystem 或 pain point），就按该方向探索，跳过下面的推断。\n- 否则，向前回看一段足够长的 commit history（`git log --oneline`），找出反复出现的 files 和 areas，让这些 hot spots 成为首要关注点。如果变更分散、没有明显 hot spot，再扩大范围。\n\n先读取项目 domain glossary（`GLOSSARY.md`）以及你将触碰区域的 ADRs。\n\n然后 spawn 一个使用全新 context window 的 sub-agent 来遍历 codebase。不要套死板 heuristics；自然探索，并记录你感到 friction 的地方：\n\n- 理解一个概念是否需要在许多小 modules 之间来回跳？\n- 哪些 modules 是 **shallow** 的，即 interface 几乎和 implementation 一样复杂？\n- 是否存在为了 testability 抽出的 pure functions，但真正 bugs 藏在它们如何被调用之处（没有 **locality**）？\n- 哪些 tightly-coupled modules 泄漏到了 seams 之外？\n- Codebase 的哪些部分未测试，或很难通过当前 interface 测试？\n\n对任何你怀疑 shallow 的东西应用 **deletion test**：删除它会让复杂度集中，还是只把复杂度移动到别处？\"yes, concentrates\" 才是你要的 signal。\n\n### 2. 用 HTML 报告呈现候选项\n\n把 self-contained HTML file 写到 OS temp directory，避免任何内容落进 repo。Temp dir 从 `$TMPDIR` 解析，fallback 到 `\u002Ftmp`（Windows 用 `%TEMP%`），写到 `\u003Ctmpdir>\u002Farchitecture-review-\u003Ctimestamp>.html`，让每次运行都有新文件。为用户打开它：Linux 用 `xdg-open \u003Cpath>`，macOS 用 `open \u003Cpath>`，Windows 用 `start \u003Cpath>`，并告诉用户 absolute path。\n\nReport 使用 **Tailwind via CDN** 做 layout\u002Fstyling，用 **Mermaid via CDN** 做能可靠传达结构的 diagrams。Mermaid 和手写 CSS\u002FSVG visuals 可以混用：关系是 graph-shaped（call graphs、dependencies、sequences）时用 Mermaid；需要 editorial 表达（mass diagrams、cross-sections、collapse animations）时用手写 divs\u002FSVG。每个 candidate 都要有 **before\u002Fafter visualisation**。要视觉化。\n\n每个 candidate 渲染一张 card，包含：\n\n- **Files** - 涉及哪些 files\u002Fmodules\n- **Problem** - 当前 architecture 为什么造成 friction\n- **Solution** - 会改变什么，用平实的语言描述\n- **Benefits** - 用 locality 与 leverage 解释收益，以及 tests 如何改善\n- **Before \u002F After diagram** - side-by-side，自绘，说明 shallowness 与 deepening\n- **Recommendation strength** - `Strong`、`Worth exploring`、`Speculative` 之一，渲染为 badge\n\nReport 末尾包含**首选推荐区**：你会先处理哪个 candidate，以及为什么。\n\n**用 `GLOSSARY.md` vocabulary 表达 domain，用 `\u002Fcodebase-design` vocabulary 表达 architecture。** 如果 `GLOSSARY.md` 定义了 \"Order\"，就说 \"Order intake module\"，不要说 \"FooBarHandler\"，也不要说 \"Order service\"。\n\n**ADR conflicts**：如果 candidate 与现有 ADR 冲突，只有在 friction 真实到值得重新打开 ADR 时才提出。Card 中明确标记（例如 warning callout：_\"contradicts ADR-0007 - but worth reopening because...\"_）。不要列出 ADR 理论上禁止的每个 refactor。\n\n完整 HTML scaffold、diagram patterns 和 styling guidance 见 [HTML-REPORT.md](HTML-REPORT.md)。\n\n现在不要提出 interfaces。写完文件后问用户：\"Which of these would you like to explore?\"\n\n### 3. Grilling 循环\n\n用户选中 candidate 后，调用 Skill 工具并指定 `grilling`，与用户走完 decision tree：constraints、dependencies、deepened module 的形状、seam 后面放什么、哪些 tests 能保留。\n\nSide effects 随 decisions 成形而内联发生；调用 Skill 工具并指定 `domain-modeling`，让 domain model 保持最新：\n\n- **要用 `GLOSSARY.md` 中不存在的概念命名 deepened module？** 把 term 加入 `GLOSSARY.md`。若文件不存在，按需创建。\n- **对话中打磨了 fuzzy term？** 立即更新 `GLOSSARY.md`。\n- **用户以 load-bearing reason 拒绝了 candidate？** 提议写 ADR，表述为：_\"Want me to record this as an ADR so future architecture reviews don't re-suggest it?\"_ 只有当未来 explorer 确实需要该 reason 以避免再次提出同样建议时才提议；跳过临时原因（\"not worth it right now\"）和显而易见原因。\n- **想探索 deepened module 的 alternative interfaces？** 调用 Skill 工具并指定 `codebase-design`，并使用其中的 design-it-twice parallel sub-agent pattern。\n",{"name":5,"description":7,"disable-model-invocation":37},true,"main","c5c5e87cc1df26aeb7dba345ad9f846434d2b3d4","skills\u002Fengineering\u002Fimprove-codebase-architecture",450,"https:\u002F\u002Fgithub.com\u002Fvinvcn\u002Fmattpocock-skills-zh-CN","https:\u002F\u002Fskills.sh\u002Fvinvcn\u002Fmattpocock-skills-zh-CN","https:\u002F\u002Fgithub.com\u002Fvinvcn","2026-11-10 17:40:42",{"source":8,"skillName":5,"commands":47,"prompt":57,"zipAvailable":37},[48,51,54],{"tool":49,"command":50},"npx","npx skills add vinvcn\u002Fmattpocock-skills-zh-CN --skill improve-codebase-architecture",{"tool":52,"command":53},"bunx","bunx skills add vinvcn\u002Fmattpocock-skills-zh-CN --skill improve-codebase-architecture",{"tool":55,"command":56},"pnpm","pnpm dlx skills add vinvcn\u002Fmattpocock-skills-zh-CN --skill improve-codebase-architecture","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fvinvcn\u002Fmattpocock-skills-zh-CN\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Fimprove-codebase-architecture\u002FSKILL.md",[59,65],{"path":60,"resourceType":61,"resourceTypeDesc":62,"sizeBytes":63,"sourceHtmlUrl":64},"agents\u002Fopenai.yaml","REFERENCE","参考文档",159,"https:\u002F\u002Fgithub.com\u002Fvinvcn\u002Fmattpocock-skills-zh-CN\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Fimprove-codebase-architecture\u002Fagents\u002Fopenai.yaml",{"path":66,"resourceType":61,"resourceTypeDesc":62,"sizeBytes":67,"sourceHtmlUrl":68},"HTML-REPORT.md",6688,"https:\u002F\u002Fgithub.com\u002Fvinvcn\u002Fmattpocock-skills-zh-CN\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Fimprove-codebase-architecture\u002FHTML-REPORT.md",[70,92,101,111,121,130],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":87,"publishedAt":32},"01M71Q8F3M8YFP6WYVYQP61KBT","writing-for-agents","为 agent 编写文档。适用于创建或编辑 skills，或修改 AGENTS.md 或 CLAUDE.md 时。","https:\u002F\u002Fgithub.com\u002Fvinvcn\u002Fmattpocock-skills-zh-CN\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fwriting-for-agents\u002FSKILL.md",[76,79,82],{"categoryNo":77,"categoryName":78,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":80,"categoryName":81,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":83,"categoryName":84,"taxonomyType":85,"taxonomyTypeDesc":86},"01JBSEEDCAT000000000000036","内容创作者","PROFESSION","适用职业",[88,89,90,91],"for","writing for agents","writing","文档",{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":32},"01M71Q8DHRPYE6R648CQ7NAHYN","wait-what","停一下：刚才那条消息没有说清楚，重新表述一遍。","https:\u002F\u002Fgithub.com\u002Fvinvcn\u002Fmattpocock-skills-zh-CN\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fwait-what\u002FSKILL.md",[],[99,100,30],"wait","wait what",{"skillNo":102,"name":103,"nameZh":6,"description":104,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":105,"categories":106,"keywords":107,"publishedAt":32},"01M71Q8C8CBSRJRP8Y0JRZ7RJ7","to-questionnaire","把你无法完整回答的 decision 转成一份交给他人填写的 questionnaire。","https:\u002F\u002Fgithub.com\u002Fvinvcn\u002Fmattpocock-skills-zh-CN\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fto-questionnaire\u002FSKILL.md",[],[108,109,110,30],"questionnaire","to questionnaire","decision",{"skillNo":112,"name":113,"nameZh":6,"description":114,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":115,"categories":116,"keywords":120,"publishedAt":32},"01M71Q8ASS9A6P84PSC02YFKHB","teach","在这个工作区中教用户一个新技能或概念。","https:\u002F\u002Fgithub.com\u002Fvinvcn\u002Fmattpocock-skills-zh-CN\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fteach\u002FSKILL.md",[117],{"categoryNo":118,"categoryName":119,"taxonomyType":85,"taxonomyTypeDesc":86},"01JBSEEDCAT000000000000039","教师与教育",[113,30],{"skillNo":122,"name":123,"nameZh":6,"description":124,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":125,"categories":126,"keywords":127,"publishedAt":32},"01M71Q89C2C2QRR3J3H64ZKH0P","handoff","把当前对话压缩成交接文档，让另一个代理接手。","https:\u002F\u002Fgithub.com\u002Fvinvcn\u002Fmattpocock-skills-zh-CN\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fhandoff\u002FSKILL.md",[],[123,30,128,129,91],"对话","压缩",{"skillNo":131,"name":132,"nameZh":6,"description":133,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":134,"categories":135,"keywords":136,"publishedAt":32},"01M71Q883CXWF0BGDQC3Y8TJZ2","grilling","围绕计划、decision 或 idea 持续追问用户。适用于用户想对自己的思路做压力测试，或使用任何 “grill” 触发措辞时。","https:\u002F\u002Fgithub.com\u002Fvinvcn\u002Fmattpocock-skills-zh-CN\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fgrilling\u002FSKILL.md",[],[132,137,138,110,139],"idea","grill","testing"]