[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M78FFPFAMDVHHRYBTECVGFFS":3,"skill-same:01M78FFPFAMDVHHRYBTECVGFFS":44},{"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":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M78FFPFAMDVHHRYBTECVGFFS","design-for-the-next-reader",null,"Design so that the next person to open this code can understand and change it — interface-first design for the reader six months out. Use when designing an API, module boundary, or data model; when naming things that other code will depend on; when taking a shortcut that should be labeled; or when deciding how to split responsibilities across files.","songjiun10-collab\u002FHncs","songjiun10-collab","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F293141730?v=4","01M78FEF4NYSK5BRK9HBBT64X1","01M78FEF5AKPHSAAMYT6249TR7",16,"MIT","https:\u002F\u002Fgithub.com\u002Fsongjiun10-collab\u002FHncs\u002Fblob\u002Fmain\u002Fsenior-engineer-mindset\u002Fdesign-for-the-next-reader\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: design-for-the-next-reader\ndescription: Design so that the next person to open this code can understand and change it — interface-first design for the reader six months out. Use when designing an API, module boundary, or data model; when naming things that other code will depend on; when taking a shortcut that should be labeled; or when deciding how to split responsibilities across files.\n---\n\n# Design for the next reader\n\nMaking it work now and making it something someone else (or future you) can understand and change in six months are different problems.\n\n## Interface first\n\nWrite the implementation first and you get an API that's **easy to build**. Write the interface first and you get one that's **easy to use**.\n\n- What should the calling code look like? **Write that call site first, before anything else.**\n- Is it hard to misuse? Does the argument order invite mix-ups? Can you make invalid states unrepresentable in the first place?\n- Is the shape and ownership of the data crossing this boundary clear?\n- A good module is deep — **a small interface hiding a lot of behavior.** If the interface is as complicated as the internals, the boundary is drawn wrong.\n- Example from this codebase: every one of Hncs's 12 brands' `apply_*` functions shares one signature — BGR `np.ndarray` in, same-shape `np.ndarray` out, image first, every other argument has a default. `tools\u002Fcli\u002Fvideo_engine.py` and `hybrid_engine\u002F` call any brand interchangeably because of that uniformity; the two documented exceptions (`apply_acros`\u002F`apply_monochrome` in `fuji.py`, which return 2D single-channel) are pinned by a golden test specifically because breaking the contract silently would ripple into every caller.\n- Principal angle: an interface used by more than one team is a promise you're making to people you'll never talk to before they build on it — design it as if you can't personally walk every caller through a breaking change later, because you won't be able to.\n- Distinguished\u002FFellow angle: if this becomes the pattern every team in the company is expected to follow, the real test is whether it still reads as obviously correct once you're no longer the one people ask — doctrine, not tribal knowledge.\n- Executive angle (CTO\u002FVP-Eng): a design only its original author can safely extend is a hiring and retention constraint — ask whether you can staff and onboard people against it, not just whether one expert can operate it.\n\n## The view from six months out\n\n- Can someone tell what this does from the name and structure alone, without reading the body?\n- If a requirement shifts slightly (one new field), does this structure absorb it, or does it need a rewrite?\n- Are you using the project's existing vocabulary? A new name for an existing concept makes the next reader think there are two different things.\n- Does this clash with the existing style? Even if your taste is better, **match the existing style.**\n\n## Label your shortcuts\n\nIf you hardcoded something, took a temporary workaround, or traded correctness for performance, **write down that you did it and why.** Code left unexplained either gets left untouched out of fear, or deleted without a thought — both are wrong outcomes.\n","# Design for the next reader\n\nMaking it work now and making it something someone else (or future you) can understand and change in six months are different problems.\n\n## Interface first\n\nWrite the implementation first and you get an API that's **easy to build**. Write the interface first and you get one that's **easy to use**.\n\n- What should the calling code look like? **Write that call site first, before anything else.**\n- Is it hard to misuse? Does the argument order invite mix-ups? Can you make invalid states unrepresentable in the first place?\n- Is the shape and ownership of the data crossing this boundary clear?\n- A good module is deep — **a small interface hiding a lot of behavior.** If the interface is as complicated as the internals, the boundary is drawn wrong.\n- Example from this codebase: every one of Hncs's 12 brands' `apply_*` functions shares one signature — BGR `np.ndarray` in, same-shape `np.ndarray` out, image first, every other argument has a default. `tools\u002Fcli\u002Fvideo_engine.py` and `hybrid_engine\u002F` call any brand interchangeably because of that uniformity; the two documented exceptions (`apply_acros`\u002F`apply_monochrome` in `fuji.py`, which return 2D single-channel) are pinned by a golden test specifically because breaking the contract silently would ripple into every caller.\n- Principal angle: an interface used by more than one team is a promise you're making to people you'll never talk to before they build on it — design it as if you can't personally walk every caller through a breaking change later, because you won't be able to.\n- Distinguished\u002FFellow angle: if this becomes the pattern every team in the company is expected to follow, the real test is whether it still reads as obviously correct once you're no longer the one people ask — doctrine, not tribal knowledge.\n- Executive angle (CTO\u002FVP-Eng): a design only its original author can safely extend is a hiring and retention constraint — ask whether you can staff and onboard people against it, not just whether one expert can operate it.\n\n## The view from six months out\n\n- Can someone tell what this does from the name and structure alone, without reading the body?\n- If a requirement shifts slightly (one new field), does this structure absorb it, or does it need a rewrite?\n- Are you using the project's existing vocabulary? A new name for an existing concept makes the next reader think there are two different things.\n- Does this clash with the existing style? Even if your taste is better, **match the existing style.**\n\n## Label your shortcuts\n\nIf you hardcoded something, took a temporary workaround, or traded correctness for performance, **write down that you did it and why.** Code left unexplained either gets left untouched out of fear, or deleted without a thought — both are wrong outcomes.\n",{"name":5,"description":7},"main","513567c2b0eb44c159ebac74b0491bdcf823c377","senior-engineer-mindset\u002Fdesign-for-the-next-reader",2,"https:\u002F\u002Fgithub.com\u002Fsongjiun10-collab\u002FHncs","https:\u002F\u002Fgithub.com\u002Fsongjiun10-collab","2026-11-07 16:34:56",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add songjiun10-collab\u002FHncs --skill design-for-the-next-reader",{"tool":36,"command":37},"bunx","bunx skills add songjiun10-collab\u002FHncs --skill design-for-the-next-reader",{"tool":39,"command":40},"pnpm","pnpm dlx skills add songjiun10-collab\u002FHncs --skill design-for-the-next-reader","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fsongjiun10-collab\u002FHncs\u002Fblob\u002Fmain\u002Fsenior-engineer-mindset\u002Fdesign-for-the-next-reader\u002FSKILL.md",true,[],[45,52,59,66,73,80],{"skillNo":46,"name":47,"nameZh":6,"description":48,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":49,"categories":50,"keywords":51,"publishedAt":18},"01M78FJ7DGE8S2MHJQY4RVTPMF","widen-the-solution-space","Deliberately widen the set of candidate approaches before committing to one. Use before irreversible decisions (architecture, DB schema, data format, public API), when the first solution feels complicated or awkward, when the user is deciding rather than instructing (\"what's the best way to do this?\"), or when a previous attempt at the same problem failed. Skip for routine work with one obvious answer.","https:\u002F\u002Fgithub.com\u002Fsongjiun10-collab\u002FHncs\u002Fblob\u002Fmain\u002Fsenior-engineer-mindset\u002Fwiden-the-solution-space\u002FSKILL.md",[],[],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":18},"01M78FJ2D6HMAGS8E11VBD4NS0","weigh-tradeoffs","Compare real alternatives explicitly and record why one was chosen. Use when picking between libraries, data structures, architectures, or storage options; when a decision is hard to reverse (schema, public API, data format, dependency); or when the user asks \"which is better, A or B\". Also use to decide how much deliberation a decision even deserves.","https:\u002F\u002Fgithub.com\u002Fsongjiun10-collab\u002FHncs\u002Fblob\u002Fmain\u002Fsenior-engineer-mindset\u002Fweigh-tradeoffs\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":18},"01M78FHX1P3QMTMC8WPQS0Z669","verify-before-claiming","Run the verification and read its output before saying anything is done, fixed, working, or passing. Use before any completion claim, before committing or opening a PR, before moving to the next task, and after a subagent or tool reports success. Triggers on the words \"should work\", \"fixed\", \"done\", \"passing\", \"looks good\" — and on the urge to celebrate.","https:\u002F\u002Fgithub.com\u002Fsongjiun10-collab\u002FHncs\u002Fblob\u002Fmain\u002Fsenior-engineer-mindset\u002Fverify-before-claiming\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":18},"01M78FHSBQ30GH1EMSBA8NJZNX","verifiability-first","Turn the task into something verifiable and declare the success criterion before seeing results. Use when the request is vague about \"done\" (\"make it work\", \"improve this\"), when writing tests, when fixing a bug (write the failing reproduction first), or when comparing two approaches. Critical before any measurement or benchmark, where deciding the bar after seeing the numbers guarantees a \"success\".","https:\u002F\u002Fgithub.com\u002Fsongjiun10-collab\u002FHncs\u002Fblob\u002Fmain\u002Fsenior-engineer-mindset\u002Fverifiability-first\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":18},"01M78FHN4P77KF3T47M1NBT7XA","threat-and-scale-check","Check trust boundaries, scale behavior, and layered safety. Use when handling user input, external API responses, files, or auth; when designing permissions, validation, or any safety mechanism; when data volume could grow; or when writing loops that touch I\u002FO. Also use when reviewing whether a single safeguard is the only thing standing between a mistake and a disaster.","https:\u002F\u002Fgithub.com\u002Fsongjiun10-collab\u002FHncs\u002Fblob\u002Fmain\u002Fsenior-engineer-mindset\u002Fthreat-and-scale-check\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":18},"01M78FHGGZKPTBRVWJK83X18CY","surgical-change","Keep every changed line traceable to the request. Use when editing existing code, especially code you didn't write; when tempted to clean up something you noticed while reading; when a diff is growing beyond the ask; or when deciding whether to delete code that looks dead.","https:\u002F\u002Fgithub.com\u002Fsongjiun10-collab\u002FHncs\u002Fblob\u002Fmain\u002Fsenior-engineer-mindset\u002Fsurgical-change\u002FSKILL.md",[],[]]