[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7ASJ7DNH3PQHASGH2D1JB77":3,"skill-same:01M7ASJ7DNH3PQHASGH2D1JB77":60},{"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":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M7ASJ7DNH3PQHASGH2D1JB77","codebase-design",null,"Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.","ozzycodes2\u002Fclaudellum","ozzycodes2","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F21285094?v=4","01M7ASJ57KTP519F96S4QGM7C5","Osniel Quintana","01M7ASJ589JS8S075AA92Y08S4",1,"MIT","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Farchitecture-design\u002Fskills\u002Fcodebase-design\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: codebase-design\ndescription: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.\n---\n\n# Codebase Design\n\nDesign **deep modules**: much behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is designed or restructured. Aim: leverage for callers, locality for maintainers, testability for everyone.\n\n## Glossary\n\nUse these terms exactly — don't substitute \"component,\" \"service,\" \"API,\" or \"boundary.\" Consistent language is the whole point.\n\n**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.\n\n**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow — type-level surface only).\n\n**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for \"adapter\" when the seam is the topic; \"implementation\" otherwise.\n\n**Depth** — leverage at the interface: behaviour a caller (or test) can exercise per unit of interface learned. A module is **deep** when much behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.\n\n**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).\n\n**Adapter** — a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).\n\n**Leverage** — what callers get from depth: more capability per unit of interface learned. One implementation pays back across N call sites and M tests.\n\n**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.\n\n## Deep vs shallow\n\n**Deep module** = small interface + lots of implementation:\n\n```\n┌─────────────────────┐\n│   Small Interface   │  ← Few methods, simple params\n├─────────────────────┤\n│                     │\n│  Deep Implementation│  ← Complex logic hidden\n│                     │\n└─────────────────────┘\n```\n\n**Shallow module** = large interface + little implementation (avoid):\n\n```\n┌─────────────────────────────────┐\n│       Large Interface           │  ← Many methods, complex params\n├─────────────────────────────────┤\n│  Thin Implementation            │  ← Just passes through\n└─────────────────────────────────┘\n```\n\nWhen designing an interface, ask:\n\n- Can I reduce the number of methods?\n- Can I simplify the parameters?\n- Can I hide more complexity inside?\n\n## Principles\n\n- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.\n- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.\n- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.\n- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.\n\n## Designing for testability\n\nGood interfaces make testing natural:\n\n1. **Accept dependencies, don't create them.**\n\n   ```typescript\n   \u002F\u002F Testable\n   function processOrder(order, paymentGateway) {}\n\n   \u002F\u002F Hard to test\n   function processOrder(order) {\n     const gateway = new StripeGateway();\n   }\n   ```\n\n2. **Return results, don't produce side effects.**\n\n   ```typescript\n   \u002F\u002F Testable\n   function calculateDiscount(cart): Discount {}\n\n   \u002F\u002F Hard to test\n   function applyDiscount(cart): void {\n     cart.total -= discount;\n   }\n   ```\n\n3. **Small surface area.** Fewer methods = fewer tests. Fewer params = simpler test setup.\n\n## Relationships\n\n- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).\n- **Depth** is a property of a **Module**, measured against its **Interface**.\n- A **Seam** is where a **Module**'s **Interface** lives.\n- An **Adapter** sits at a **Seam** and satisfies the **Interface**.\n- **Depth** produces **Leverage** for callers and **Locality** for maintainers.\n\n## Rejected framings\n\n- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. Use depth-as-leverage instead.\n- **\"Interface\" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.\n- **\"Boundary\"**: overloaded with DDD's bounded context. Say **seam** or **interface**.\n\n## Going deeper\n\n- **Deepening a cluster given its dependencies** — see [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.\n- **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.\n","# Codebase Design\n\nDesign **deep modules**: much behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is designed or restructured. Aim: leverage for callers, locality for maintainers, testability for everyone.\n\n## Glossary\n\nUse these terms exactly — don't substitute \"component,\" \"service,\" \"API,\" or \"boundary.\" Consistent language is the whole point.\n\n**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.\n\n**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow — type-level surface only).\n\n**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for \"adapter\" when the seam is the topic; \"implementation\" otherwise.\n\n**Depth** — leverage at the interface: behaviour a caller (or test) can exercise per unit of interface learned. A module is **deep** when much behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.\n\n**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).\n\n**Adapter** — a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).\n\n**Leverage** — what callers get from depth: more capability per unit of interface learned. One implementation pays back across N call sites and M tests.\n\n**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.\n\n## Deep vs shallow\n\n**Deep module** = small interface + lots of implementation:\n\n```\n┌─────────────────────┐\n│   Small Interface   │  ← Few methods, simple params\n├─────────────────────┤\n│                     │\n│  Deep Implementation│  ← Complex logic hidden\n│                     │\n└─────────────────────┘\n```\n\n**Shallow module** = large interface + little implementation (avoid):\n\n```\n┌─────────────────────────────────┐\n│       Large Interface           │  ← Many methods, complex params\n├─────────────────────────────────┤\n│  Thin Implementation            │  ← Just passes through\n└─────────────────────────────────┘\n```\n\nWhen designing an interface, ask:\n\n- Can I reduce the number of methods?\n- Can I simplify the parameters?\n- Can I hide more complexity inside?\n\n## Principles\n\n- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.\n- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.\n- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.\n- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.\n\n## Designing for testability\n\nGood interfaces make testing natural:\n\n1. **Accept dependencies, don't create them.**\n\n   ```typescript\n   \u002F\u002F Testable\n   function processOrder(order, paymentGateway) {}\n\n   \u002F\u002F Hard to test\n   function processOrder(order) {\n     const gateway = new StripeGateway();\n   }\n   ```\n\n2. **Return results, don't produce side effects.**\n\n   ```typescript\n   \u002F\u002F Testable\n   function calculateDiscount(cart): Discount {}\n\n   \u002F\u002F Hard to test\n   function applyDiscount(cart): void {\n     cart.total -= discount;\n   }\n   ```\n\n3. **Small surface area.** Fewer methods = fewer tests. Fewer params = simpler test setup.\n\n## Relationships\n\n- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).\n- **Depth** is a property of a **Module**, measured against its **Interface**.\n- A **Seam** is where a **Module**'s **Interface** lives.\n- An **Adapter** sits at a **Seam** and satisfies the **Interface**.\n- **Depth** produces **Leverage** for callers and **Locality** for maintainers.\n\n## Rejected framings\n\n- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. Use depth-as-leverage instead.\n- **\"Interface\" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.\n- **\"Boundary\"**: overloaded with DDD's bounded context. Say **seam** or **interface**.\n\n## Going deeper\n\n- **Deepening a cluster given its dependencies** — see [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.\n- **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.\n",{"name":5,"description":7},"main","a3f19bcc313571bff79dca391a83f9c4d38bb335","architecture-design\u002Fskills\u002Fcodebase-design",0,"https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum","https:\u002F\u002Fgithub.com\u002Fozzycodes2","Software Engineer | Engineering Manager | AI whisperer | ☕Enjoyer","2026-11-14 04:50:11",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add ozzycodes2\u002Fclaudellum --skill codebase-design",{"tool":38,"command":39},"bunx","bunx skills add ozzycodes2\u002Fclaudellum --skill codebase-design",{"tool":41,"command":42},"pnpm","pnpm dlx skills add ozzycodes2\u002Fclaudellum --skill codebase-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Farchitecture-design\u002Fskills\u002Fcodebase-design\u002FSKILL.md",true,[46,52,56],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"agents\u002Fopenai.yaml","REFERENCE","参考文档",102,"https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Farchitecture-design\u002Fskills\u002Fcodebase-design\u002Fagents\u002Fopenai.yaml",{"path":53,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":54,"sourceHtmlUrl":55},"DEEPENING.md",2559,"https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Farchitecture-design\u002Fskills\u002Fcodebase-design\u002FDEEPENING.md",{"path":57,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":58,"sourceHtmlUrl":59},"DESIGN-IT-TWICE.md",2691,"https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Farchitecture-design\u002Fskills\u002Fcodebase-design\u002FDESIGN-IT-TWICE.md",[61,68,75,82,89,96],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M7ASQB3CTKMKDNAXD9DCF1YC","writing-design-docs","Use when the user wants to write a problem-statement design doc, says \"let's plan a feature properly\" \u002F \"write a design doc\" \u002F \"I'm thinking about how to do X\" for a non-trivial X, or before committing to a non-obvious technical direction","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Fwriting-design-docs\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M7ASQ6JD4QRV5ZKK2QME401Y","write-doc","Use when the user asks to write or draft a README, ADR, runbook, tutorial, how-to, explanation, or reference doc, or a caller passes \"type ADR\" or \"type README\". Picks the type, fills a template, adds diagrams. RFCs and design docs belong to writing-design-docs.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Fwrite-doc\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M7ASQ1VWNVP1RE7M5D4G2QMG","review-doc","Use when the user asks to review, critique, score, grade, or \"how good is this doc\" for a Markdown doc or pasted text. Read-only. Scores it on the 20 Practical Prose dimensions and emits a findings table. Does not edit; fix-doc applies the findings next.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Freview-doc\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M7ASPWST208JZNR7HF7J6KMV","fix-doc","Use when the user asks to fix, edit for prose quality, polish, tighten, humanize, or de-slop a Markdown doc or pasted text, or says \"make this read less AI\". Applies review-doc findings, generates flagged diagrams, lists substantive issues for the author, then runs the AI-tell pass last. Modifies the target.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Ffix-doc\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M7ASPS6Y9ZGK9KCDHNPDR75A","create-slides","Use when the user asks for a slide deck, presentation, talk, or slides from a document, report, PR, notes, or topic. Builds one self-contained Machinify-branded HTML deck in a minimalist style, with headline-plus-visual slides, speaker notes, and every diagram drawn by architecture-design:create-diagram.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Fcreate-slides\u002FSKILL.md",[],[],{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":19},"01M7ASPAKFY045KHR92Y4QFTWV","start-session","Open a Claude Code working session in a fresh, isolated git worktree, so the user can start a task with a single \u002Fstart-session \u003Cname>. Use at the START of a session when the user says \"start session\", \"start a worktree\", \"spin up a worktree for ABC-123\", \"begin work on \u003Cticket>\", or passes a name\u002Fticket to work under. Creates and ENTERS a worktree via the EnterWorktree tool (never `git worktree add`) under .claude\u002Fworktrees\u002F, named exactly after the argument, on a local branch `worktree-\u003Cargument>`. Reports what the worktree inherited (`.worktreeinclude` copies, symlinked node_modules) and whether its `.env` still points at the main checkout's stack. If the argument is a JIRA key (e.g. ABC-123, PROJ-1505), also loads that story with the Atlassian CLI (`acli`) when available and summarizes the implementation ask. Also renames the session to the argument (the same effect as `\u002Frename \u003CNAME>`) so it's easy to find in `\u002Fresume`. Then stops and waits — it sets up the workspace and context, it does not implement.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Fsession-mgmt\u002Fskills\u002Fstart-session\u002FSKILL.md",[],[]]