[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AAS9YQK36ZXYZ8GDVC7EH7":3,"skill-same:01M7AAS9YQK36ZXYZ8GDVC7EH7":57},{"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":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":13,"repositoryHtmlUrl":26,"repositoryHomepageUrl":6,"ownerHtmlUrl":27,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":28,"install":29,"resources":42},"01M7AAS9YQK36ZXYZ8GDVC7EH7","codebase-design",null,"設計 deep module 的共通 vocabulary。使用於設計或改善 module interface、尋找 deepening opportunity、決定 seam、提升 testability／AI-navigability，或其他 skill 需要 deep-module vocabulary 時。","Andy-CH-BO-AN\u002Fplaywright-self-healing-tests","Andy-CH-BO-AN","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F58759761?v=4","01M71FSKGT9TWBMY2SFP4V2JR8","01M7AAS4QMEMT1S49WSF8H4NWE",0,"MIT","https:\u002F\u002Fgithub.com\u002FAndy-CH-BO-AN\u002Fplaywright-self-healing-tests\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcodebase-design\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: codebase-design\ndescription: 設計 deep module 的共通 vocabulary。使用於設計或改善 module interface、尋找 deepening opportunity、決定 seam、提升 testability／AI-navigability，或其他 skill 需要 deep-module vocabulary 時。\n---\n\n# Codebase Design\n\n設計 **deep module**：用小 interface 隱藏大量 behavior，放在乾淨 seam，並能透過該 interface 測試。所有設計／重構都應使用以下語言與原則。目標是為 caller 提供 leverage、為 maintainer 提供 locality、並提升所有人的 testability。\n\n## Glossary\n\n必須精確使用這些詞，不可替換為「component」、「service」、「API」或「boundary」。一致 vocabulary 是核心。\n\n- **Module**：任何具有 interface 與 implementation 的事物；刻意不限制尺度，可為 function、class、package 或跨 tier slice。_Avoid_: unit, component, service。\n- **Interface**：caller 正確使用 module 所需知道的一切：type signature、invariant、ordering constraint、error mode、required configuration、performance characteristic。_Avoid_: API、signature（過窄，僅指 type-level surface）。\n- **Implementation**：module 內部的 code body。不同於 **Adapter**：事物可以是小 adapter 配大 implementation（Postgres repo），或大 adapter 配小 implementation（in-memory fake）。seam 是主題時用 adapter，否則用 implementation。\n- **Depth**：interface 所帶來的 leverage；caller／test 每學習一單位 interface 能運用多少 behavior。大量 behavior 藏在小 interface 後為 **deep**；interface 幾乎與 implementation 一樣複雜為 **shallow**。\n- **Seam**（Michael Feathers）：可在不修改該處的情況下改變 behavior 的位置，也就是 module interface 所在位置。seam 放置位置是獨立設計決策，不等於其背後內容。_Avoid_: boundary（與 DDD bounded context 意義重疊）。\n- **Adapter**：在 seam 滿足 interface 的 concrete thing。描述 role（填補哪個 slot），不是內部 substance。\n- **Leverage**：depth 帶給 caller 的收益；每單位要學習的 interface 提供更多 capability。一份 implementation 回饋 N 個 call site 與 M 個 test。\n- **Locality**：depth 帶給 maintainer 的收益；change、bug、knowledge、verification 集中一處，而不分散至 callers。修一次，全部修正。\n\n## Deep 與 shallow\n\n**Deep module** 是小 interface 加大量 implementation；**shallow module** 則是大 interface 加少量 implementation，應避免。設計 interface 時問：能否減少 method？能否簡化 parameter？能否在內部隱藏更多 complexity？\n\n## 原則\n\n- **Depth 是 interface 的屬性，不是 implementation。**deep module 可在內部由小、可 mock、可替換 parts 組成；它們不屬於 interface。module 可有供自身 test 使用的 internal seam，以及 interface 上的 external seam。\n- **Deletion test。**想像刪除 module。complexity 消失代表它是 pass-through；若 complexity 在 N 個 caller 重現，代表它有價值。\n- **Interface 是 test surface。**caller 與 test 跨越相同 seam。若要測到 interface 之後，module 的 shape 多半不對。\n- **一個 adapter 是 hypothetical seam，兩個 adapter 才是 real seam。**沒有真正變異時不可引入 seam。\n\n## 為 testability 設計\n\n1. 接受 dependency，不在內部建立 dependency。\n2. 回傳 result，不只產生 side effect。\n3. 小 surface area：method 越少，test 越少；parameter 越少，setup 越簡單。\n\n## 關係\n\nModule 只有一個提供給 caller 與 test 的 Interface；Depth 由 Module 相對於 Interface 衡量；Seam 是 Interface 所在；Adapter 位於 Seam 並滿足 Interface；Depth 產生 caller 的 Leverage 與 maintainer 的 Locality。\n\n## 不採用的 framing\n\n- 不將 depth 視為 implementation line 與 interface line 比率（Ousterhout）：會鼓勵灌水 implementation；採 depth-as-leverage。\n- 不將 Interface 侷限於 TypeScript `interface` keyword 或 class public method：它也包括 caller 必須知道的所有事實。\n- 不說「Boundary」：它與 DDD bounded context 意義重疊；使用 **seam** 或 **interface**。\n\n## 延伸閱讀\n\n- 依 dependency 深化 shallow module cluster：見 [DEEPENING.md](DEEPENING.md)。\n- 探索 alternative interface：見 [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md)。\n","# Codebase Design\n\n設計 **deep module**：用小 interface 隱藏大量 behavior，放在乾淨 seam，並能透過該 interface 測試。所有設計／重構都應使用以下語言與原則。目標是為 caller 提供 leverage、為 maintainer 提供 locality、並提升所有人的 testability。\n\n## Glossary\n\n必須精確使用這些詞，不可替換為「component」、「service」、「API」或「boundary」。一致 vocabulary 是核心。\n\n- **Module**：任何具有 interface 與 implementation 的事物；刻意不限制尺度，可為 function、class、package 或跨 tier slice。_Avoid_: unit, component, service。\n- **Interface**：caller 正確使用 module 所需知道的一切：type signature、invariant、ordering constraint、error mode、required configuration、performance characteristic。_Avoid_: API、signature（過窄，僅指 type-level surface）。\n- **Implementation**：module 內部的 code body。不同於 **Adapter**：事物可以是小 adapter 配大 implementation（Postgres repo），或大 adapter 配小 implementation（in-memory fake）。seam 是主題時用 adapter，否則用 implementation。\n- **Depth**：interface 所帶來的 leverage；caller／test 每學習一單位 interface 能運用多少 behavior。大量 behavior 藏在小 interface 後為 **deep**；interface 幾乎與 implementation 一樣複雜為 **shallow**。\n- **Seam**（Michael Feathers）：可在不修改該處的情況下改變 behavior 的位置，也就是 module interface 所在位置。seam 放置位置是獨立設計決策，不等於其背後內容。_Avoid_: boundary（與 DDD bounded context 意義重疊）。\n- **Adapter**：在 seam 滿足 interface 的 concrete thing。描述 role（填補哪個 slot），不是內部 substance。\n- **Leverage**：depth 帶給 caller 的收益；每單位要學習的 interface 提供更多 capability。一份 implementation 回饋 N 個 call site 與 M 個 test。\n- **Locality**：depth 帶給 maintainer 的收益；change、bug、knowledge、verification 集中一處，而不分散至 callers。修一次，全部修正。\n\n## Deep 與 shallow\n\n**Deep module** 是小 interface 加大量 implementation；**shallow module** 則是大 interface 加少量 implementation，應避免。設計 interface 時問：能否減少 method？能否簡化 parameter？能否在內部隱藏更多 complexity？\n\n## 原則\n\n- **Depth 是 interface 的屬性，不是 implementation。**deep module 可在內部由小、可 mock、可替換 parts 組成；它們不屬於 interface。module 可有供自身 test 使用的 internal seam，以及 interface 上的 external seam。\n- **Deletion test。**想像刪除 module。complexity 消失代表它是 pass-through；若 complexity 在 N 個 caller 重現，代表它有價值。\n- **Interface 是 test surface。**caller 與 test 跨越相同 seam。若要測到 interface 之後，module 的 shape 多半不對。\n- **一個 adapter 是 hypothetical seam，兩個 adapter 才是 real seam。**沒有真正變異時不可引入 seam。\n\n## 為 testability 設計\n\n1. 接受 dependency，不在內部建立 dependency。\n2. 回傳 result，不只產生 side effect。\n3. 小 surface area：method 越少，test 越少；parameter 越少，setup 越簡單。\n\n## 關係\n\nModule 只有一個提供給 caller 與 test 的 Interface；Depth 由 Module 相對於 Interface 衡量；Seam 是 Interface 所在；Adapter 位於 Seam 並滿足 Interface；Depth 產生 caller 的 Leverage 與 maintainer 的 Locality。\n\n## 不採用的 framing\n\n- 不將 depth 視為 implementation line 與 interface line 比率（Ousterhout）：會鼓勵灌水 implementation；採 depth-as-leverage。\n- 不將 Interface 侷限於 TypeScript `interface` keyword 或 class public method：它也包括 caller 必須知道的所有事實。\n- 不說「Boundary」：它與 DDD bounded context 意義重疊；使用 **seam** 或 **interface**。\n\n## 延伸閱讀\n\n- 依 dependency 深化 shallow module cluster：見 [DEEPENING.md](DEEPENING.md)。\n- 探索 alternative interface：見 [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md)。\n",{"name":5,"description":7},"main","41b33db37e0cff05594180ed30962ae769bb66f6",".agents\u002Fskills\u002Fcodebase-design","https:\u002F\u002Fgithub.com\u002FAndy-CH-BO-AN\u002Fplaywright-self-healing-tests","https:\u002F\u002Fgithub.com\u002FAndy-CH-BO-AN","2026-09-19 18:58:37",{"source":8,"skillName":5,"commands":30,"prompt":40,"zipAvailable":41},[31,34,37],{"tool":32,"command":33},"npx","npx skills add Andy-CH-BO-AN\u002Fplaywright-self-healing-tests --skill codebase-design",{"tool":35,"command":36},"bunx","bunx skills add Andy-CH-BO-AN\u002Fplaywright-self-healing-tests --skill codebase-design",{"tool":38,"command":39},"pnpm","pnpm dlx skills add Andy-CH-BO-AN\u002Fplaywright-self-healing-tests --skill codebase-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FAndy-CH-BO-AN\u002Fplaywright-self-healing-tests\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcodebase-design\u002FSKILL.md",true,[43,49,53],{"path":44,"resourceType":45,"resourceTypeDesc":46,"sizeBytes":47,"sourceHtmlUrl":48},"agents\u002Fopenai.yaml","REFERENCE","参考文档",113,"https:\u002F\u002Fgithub.com\u002FAndy-CH-BO-AN\u002Fplaywright-self-healing-tests\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcodebase-design\u002Fagents\u002Fopenai.yaml",{"path":50,"resourceType":45,"resourceTypeDesc":46,"sizeBytes":51,"sourceHtmlUrl":52},"DEEPENING.md",2290,"https:\u002F\u002Fgithub.com\u002FAndy-CH-BO-AN\u002Fplaywright-self-healing-tests\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcodebase-design\u002FDEEPENING.md",{"path":54,"resourceType":45,"resourceTypeDesc":46,"sizeBytes":55,"sourceHtmlUrl":56},"DESIGN-IT-TWICE.md",1950,"https:\u002F\u002Fgithub.com\u002FAndy-CH-BO-AN\u002Fplaywright-self-healing-tests\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcodebase-design\u002FDESIGN-IT-TWICE.md",[58,65,72,79,86,93],{"skillNo":59,"name":60,"nameZh":6,"description":61,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":18},"01M7AASPR946YZRE5RF4A9Y712","readme-pm-review","僅在使用者明確要求以 product-manager 角度審查 repository README 時使用。先只讀 README，不推測未記錄功能，提供可讀性回饋、改寫建議與產品優先順序建議。","https:\u002F\u002Fgithub.com\u002FAndy-CH-BO-AN\u002Fplaywright-self-healing-tests\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Freadme-pm-review\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":18},"01M7AASN0CP3ET98VX899G692M","improve-codebase-architecture","掃描 codebase 的 deepening 機會，以視覺化 HTML report 呈現，並針對使用者選擇的項目進行 grilling。","https:\u002F\u002Fgithub.com\u002FAndy-CH-BO-AN\u002Fplaywright-self-healing-tests\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fimprove-codebase-architecture\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":18},"01M7AASKTD9ZN18D6NTKKW1MXH","handoff","將目前對話濃縮為可供下一位 agent 接手的交接文件。","https:\u002F\u002Fgithub.com\u002FAndy-CH-BO-AN\u002Fplaywright-self-healing-tests\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fhandoff\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":18},"01M7AASJGF9S5PYDPX06TE8SAP","grilling","以密集提問檢驗使用者的計畫、決策或想法。使用者想壓力測試思考或使用任何「grill」觸發語時使用。","https:\u002F\u002Fgithub.com\u002FAndy-CH-BO-AN\u002Fplaywright-self-healing-tests\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fgrilling\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":18},"01M7AASH7K8B19AZ6Z5FF1TRDB","grill-with-docs","以密集訪談釐清並磨練計畫或設計，並同步建立 ADR 與 glossary 文件。","https:\u002F\u002Fgithub.com\u002FAndy-CH-BO-AN\u002Fplaywright-self-healing-tests\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fgrill-with-docs\u002FSKILL.md",[],[],{"skillNo":94,"name":95,"nameZh":6,"description":96,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":18},"01M7AASG4404RPT22AMJX2PMP9","grill-me","以密集訪談釐清並磨練計畫或設計。","https:\u002F\u002Fgithub.com\u002FAndy-CH-BO-AN\u002Fplaywright-self-healing-tests\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fgrill-me\u002FSKILL.md",[],[]]