[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6KWZ5K17HNWJ5991GYDZPWP":3,"skill-same:01M6KWZ5K17HNWJ5991GYDZPWP":90},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":28,"publishedAt":48,"linkOnly":49,"markdownContent":50,"markdownBody":51,"frontMatter":52,"refName":53,"commitSha":54,"skillDirectory":55,"forksCount":56,"repositoryHtmlUrl":57,"repositoryHomepageUrl":6,"ownerHtmlUrl":58,"ownerBlogUrl":59,"ownerDescription":60,"updatedAt":61,"install":62,"resources":75},"01M6KWZ5K17HNWJ5991GYDZPWP","codebase-design",null,"Shared vocabulary and principles for designing deep modules: a lot of behaviour behind a small interface, at a clean seam, testable through that interface. Use when designing or reshaping a module's interface, deciding where a seam goes, making code more testable or easier for agents to navigate, and when another skill needs the deep-module vocabulary.","dougborg\u002Fharness-kit","dougborg","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F1261222?v=4","01M6KWS4PB51EYD4ZDJJSGNGB2","Doug Borg","01M6KWS4T8ZZW6SX5QZS9B5BN2",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Fcodebase-design\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47],"codebase design","design","codebase","seam","for","at","more","goes","interface","principles","module","deep","shared","another skill","vocabulary","clean","modules","use","code","2026-11-10 10:12:30",false,"---\nname: codebase-design\ndescription: >-\n  Shared vocabulary and principles for designing deep modules: a lot of\n  behaviour behind a small interface, at a clean seam, testable through that\n  interface. Use when designing or reshaping a module's interface, deciding\n  where a seam goes, making code more testable or easier for agents to\n  navigate, and when another skill needs the deep-module vocabulary.\n---\n\n# Codebase Design\n\nDesign **deep modules**: a lot of behaviour behind a small interface, placed at\na clean seam, testable through that interface. The aim is leverage for\ncallers, locality for maintainers, and testability for everyone.\n\n## Vocabulary\n\nUse these terms exactly; consistent words are the point.\n\n- **Module**: anything with an interface and an implementation, at any scale:\n  a function, class, package, or slice across tiers. _Avoid_: unit,\n  component, service.\n- **Interface**: everything a caller must know to use the module correctly:\n  the signature plus invariants, ordering constraints, error modes, required\n  configuration, and performance characteristics. _Avoid_: API, signature\n  (both name only the type-level surface).\n- **Implementation**: the code inside a module.\n- **Depth**: leverage at the interface, the behaviour a caller or test can\n  exercise per unit of interface they have to learn. The deep-module idea is\n  Ousterhout's; measuring it as leverage rather than as a ratio of\n  implementation lines to interface lines is deliberate, since a line ratio\n  rewards padding. **Deep**: much behaviour\n  behind a small interface. **Shallow**: the interface is nearly as complex as\n  the implementation.\n- **Seam** (Michael Feathers): a place where behaviour can change without\n  editing that place; where a module's interface lives. Where to put it is a\n  design decision of its own. _Avoid_: boundary (overloaded with DDD's bounded\n  context).\n- **Adapter**: a concrete thing that satisfies an interface at a seam. It names\n  a role, not a size: a thin adapter can wrap a large implementation.\n- **Leverage**: what callers gain from depth; one implementation pays back\n  across many call sites and tests.\n- **Locality**: what maintainers gain from depth; change, bugs, and knowledge\n  concentrate in one place.\n\n## Principles\n\n- **Depth belongs to the interface.** A deep module can be built from small,\n  swappable parts inside; they just aren't part of its interface. A module can\n  have internal seams for its own tests as well as the external seam callers\n  use.\n- **The deletion test.** Imagine deleting the module. If complexity vanishes,\n  it was a pass-through. If complexity reappears across many callers, it was\n  earning its keep.\n- **The interface is the test surface.** Callers and tests cross the same\n  seam. Wanting to test past the interface means the module is the wrong\n  shape.\n- **One adapter means a hypothetical seam; two adapters mean a real one.**\n  Introduce a seam only when something actually varies across it (typically\n  production and test).\n\n## Designing for testability\n\n- **Accept dependencies; don't construct them.** `processOrder(order,\n  paymentGateway)` is testable; a function that builds its own gateway is not.\n- **Return results rather than producing side effects** where the caller can\n  apply them: `calculateDiscount(cart): Discount` over\n  `applyDiscount(cart): void`.\n- **Keep the surface small.** Fewer methods mean fewer tests; fewer\n  parameters mean simpler setup. For any interface, ask: can it have fewer\n  methods, simpler parameters, or hide more inside?\n\n## Going deeper\n\n- Deepening a cluster of shallow modules given their dependencies (in-process,\n  local stand-in, remote but owned, true external), seam discipline, and\n  replacing old tests rather than layering on them:\n  [DEEPENING.md](DEEPENING.md).\n- Exploring alternative interfaces with parallel subagents, each designing\n  under a different constraint, then comparing on depth, locality, and seam\n  placement: [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md).\n","# Codebase Design\n\nDesign **deep modules**: a lot of behaviour behind a small interface, placed at\na clean seam, testable through that interface. The aim is leverage for\ncallers, locality for maintainers, and testability for everyone.\n\n## Vocabulary\n\nUse these terms exactly; consistent words are the point.\n\n- **Module**: anything with an interface and an implementation, at any scale:\n  a function, class, package, or slice across tiers. _Avoid_: unit,\n  component, service.\n- **Interface**: everything a caller must know to use the module correctly:\n  the signature plus invariants, ordering constraints, error modes, required\n  configuration, and performance characteristics. _Avoid_: API, signature\n  (both name only the type-level surface).\n- **Implementation**: the code inside a module.\n- **Depth**: leverage at the interface, the behaviour a caller or test can\n  exercise per unit of interface they have to learn. The deep-module idea is\n  Ousterhout's; measuring it as leverage rather than as a ratio of\n  implementation lines to interface lines is deliberate, since a line ratio\n  rewards padding. **Deep**: much behaviour\n  behind a small interface. **Shallow**: the interface is nearly as complex as\n  the implementation.\n- **Seam** (Michael Feathers): a place where behaviour can change without\n  editing that place; where a module's interface lives. Where to put it is a\n  design decision of its own. _Avoid_: boundary (overloaded with DDD's bounded\n  context).\n- **Adapter**: a concrete thing that satisfies an interface at a seam. It names\n  a role, not a size: a thin adapter can wrap a large implementation.\n- **Leverage**: what callers gain from depth; one implementation pays back\n  across many call sites and tests.\n- **Locality**: what maintainers gain from depth; change, bugs, and knowledge\n  concentrate in one place.\n\n## Principles\n\n- **Depth belongs to the interface.** A deep module can be built from small,\n  swappable parts inside; they just aren't part of its interface. A module can\n  have internal seams for its own tests as well as the external seam callers\n  use.\n- **The deletion test.** Imagine deleting the module. If complexity vanishes,\n  it was a pass-through. If complexity reappears across many callers, it was\n  earning its keep.\n- **The interface is the test surface.** Callers and tests cross the same\n  seam. Wanting to test past the interface means the module is the wrong\n  shape.\n- **One adapter means a hypothetical seam; two adapters mean a real one.**\n  Introduce a seam only when something actually varies across it (typically\n  production and test).\n\n## Designing for testability\n\n- **Accept dependencies; don't construct them.** `processOrder(order,\n  paymentGateway)` is testable; a function that builds its own gateway is not.\n- **Return results rather than producing side effects** where the caller can\n  apply them: `calculateDiscount(cart): Discount` over\n  `applyDiscount(cart): void`.\n- **Keep the surface small.** Fewer methods mean fewer tests; fewer\n  parameters mean simpler setup. For any interface, ask: can it have fewer\n  methods, simpler parameters, or hide more inside?\n\n## Going deeper\n\n- Deepening a cluster of shallow modules given their dependencies (in-process,\n  local stand-in, remote but owned, true external), seam discipline, and\n  replacing old tests rather than layering on them:\n  [DEEPENING.md](DEEPENING.md).\n- Exploring alternative interfaces with parallel subagents, each designing\n  under a different constraint, then comparing on depth, locality, and seam\n  placement: [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md).\n",{"name":5,"description":7},"main","023b01bfb4a86fbf1e38a749f1044cce3e5da67d","skills\u002Fengineering\u002Fcodebase-design",1,"https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit","https:\u002F\u002Fgithub.com\u002Fdougborg","http:\u002F\u002Fdougborg.org","Platforms and Infrastructure Software Engineer","2026-11-13 07:43:37",{"source":8,"skillName":5,"commands":63,"prompt":73,"zipAvailable":74},[64,67,70],{"tool":65,"command":66},"npx","npx skills add dougborg\u002Fharness-kit --skill codebase-design",{"tool":68,"command":69},"bunx","bunx skills add dougborg\u002Fharness-kit --skill codebase-design",{"tool":71,"command":72},"pnpm","pnpm dlx skills add dougborg\u002Fharness-kit --skill codebase-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Fcodebase-design\u002FSKILL.md",true,[76,82,86],{"path":77,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":80,"sourceHtmlUrl":81},"agents\u002Fopenai.yaml","REFERENCE","参考文档",122,"https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Fcodebase-design\u002Fagents\u002Fopenai.yaml",{"path":83,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":84,"sourceHtmlUrl":85},"DEEPENING.md",1657,"https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Fcodebase-design\u002FDEEPENING.md",{"path":87,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":88,"sourceHtmlUrl":89},"DESIGN-IT-TWICE.md",1747,"https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Fcodebase-design\u002FDESIGN-IT-TWICE.md",[91,108,127,157,181,198],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":100,"publishedAt":48},"01M6KX4J65S5FZKMSN5DQNPSZM","teach","Teach yourself a topic over several sessions, with lessons, references, and a record of what you've learned.","https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting\u002Fteach\u002FSKILL.md",[97],{"categoryNo":98,"categoryName":99,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000039","教师与教育",[93,101,102,103,104,105,106,107],"lessons","you","with","learned","record","references","sessions",{"skillNo":109,"name":110,"nameZh":6,"description":111,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":112,"categories":113,"keywords":117,"publishedAt":48},"01M6KX4FSSG7MHF00JDT5QT0BQ","svg-logo-designer","Generate SVG logos with multiple concepts, layouts, and color variations.","https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting\u002Fsvg-logo-designer\u002FSKILL.md",[114],{"categoryNo":115,"categoryName":116,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000016","图像与多媒体",[118,119,120,121,122,123,103,124,125,126],"logo","designer","svg logo designer","SVG","color","concepts","write","read","generate",{"skillNo":128,"name":129,"nameZh":6,"description":130,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":131,"categories":132,"keywords":139,"publishedAt":48},"01M6KX4BD3J9MZPPSH4MENH7FP","documentation-writer","Writes and revises human-facing documentation — READMEs, contributor and setup guides, reference pages, architecture notes, CLAUDE.md, and changelog entries. Covers picking the right document type for the question being asked, structuring for skimming, writing examples that actually run, and keeping docs from going stale. Use when creating or rewriting docs, when a README has drifted from the code, or when deciding where a piece of information belongs. For SKILL.md and agent files, use \u002Fskill-writer instead.","https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting\u002Fdocumentation-writer\u002FSKILL.md",[133,136],{"categoryNo":134,"categoryName":135,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":137,"categoryName":138,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000036","内容创作者",[140,141,142,143,144,145,146,147,46,148,149,150,47,151,152,33,153,154,155,156],"writer","documentation writer","documentation","entries","changelog","architecture","document","files","question","README","notes","examples","pages","information","guides","type","writing",{"skillNo":158,"name":159,"nameZh":6,"description":160,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":161,"categories":162,"keywords":163,"publishedAt":48},"01M6KX47ZJ4ZWHDN3MY8SYAWZZ","adhd-mode","Shapes every response for a reader with ADHD: the next action first, numbered steps, progress restated each turn, tangents held back, concrete time estimates, wins made visible. Stays on for the rest of the session until the reader says \"stop adhd mode\". On Claude Code, the harness-kit:adhd output style does the same without invoking this skill.","https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting\u002Fadhd-mode\u002FSKILL.md",[],[164,165,166,167,33,168,169,103,170,171,172,173,174,175,176,177,178,179,180,47],"adhd","mode","adhd mode","next","action","kit","output","style","progress","time","back","stop","session","reader","first","REST","harness",{"skillNo":182,"name":183,"nameZh":6,"description":184,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":185,"categories":186,"keywords":187,"publishedAt":48},"01M6KX463Z6E18EPDW873GDHKB","wait-what","That last message didn't land: re-explain it with the missing context.","https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fthinking\u002Fwait-what\u002FSKILL.md",[],[188,189,190,103,191,192,193,194,195,196,197],"wait","wait what","re","it","missing","message","context","explain","land","last",{"skillNo":199,"name":200,"nameZh":6,"description":201,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":202,"categories":203,"keywords":204,"publishedAt":48},"01M6KX43NE1NB0Y2HECY515730","to-questionnaire","Turn a decision you can't make alone into a questionnaire for the one person who can answer it, filled in async or together in a meeting.","https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fthinking\u002Fto-questionnaire\u002FSKILL.md",[],[205,206,33,207,208,209,210,102,211,191,212,213],"to questionnaire","questionnaire","person","can","answer","meeting","make","async","decision"]