القائمة
Use when building an app that touches external systems (LLMs, DBs, cloud SDKs, HTTP APIs) — isolate a framework-free core behind ports a linter enforces.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when wiring a project's dev workflow (local stack, test tiers, gates, docs), or when naming make targets in a repo that has siblings — build a thin self-documenting Makefile facade over real scripts, name targets from the shared cross-repo vocabulary, and split env files by owner so targets consume them but never write them.
Use when you need to prove a feature actually delivers its intended outcome to a user or caller, not just that its code paths run — write executable acceptance tests against real, observable outcomes, derived from the spec before or independent of the implementation.
Use when adding any new capability to a working system — ship it behind a flag or optional collaborator that defaults to prior behavior.
Use when a spec, plan, or implementation must be independently reviewed before it is trusted, committed, or advanced to the next phase — dispatch a fresh reviewer per named lens whose job is to refute the artifact, not confirm it.
Use when building automation that edits, tests, or deploys itself — an agent that regenerates its own code, a self-updating pipeline, any loop that modifies the thing running it.
Use when about to call any integration, deployment, or hard guarantee "done" — prove it live end-to-end and capture the run as evidence.
| name | hexagonal-with-enforced-contracts |
| description | Use when building an app that touches external systems (LLMs, DBs, cloud SDKs, HTTP APIs) — isolate a framework-free core behind ports a linter enforces. |
Put your business logic in a core that imports no framework or SDK, reach every external system through a Protocol/interface port, and let an automated import-checker — not reviewer discipline — fail the build when anything inner imports anything outer.
Reach for this whenever an app integrates volatile externals — LLM providers, databases, cloud SDKs, message queues, third-party HTTP APIs — and you want those choices to stay swappable and testable.
Red-flag thoughts that mean STOP and apply this skill:
Any/object for now and type it later."Any/object/interface{}/dynamic, the layer secretly depends on the implementation. Give it a real port type, and pin each adapter to its port with a conformance test (instantiate the adapter, assert it satisfies the port).make check, npm run verify, a pre-merge job — whatever your gate is). A boundary violation must fail the build exactly like a failing test.Architecture maintained by vigilance decays: every PR is a fresh chance for an SDK import to slip into the core, and reviewers miss it. A linter contract converts "we agreed not to do that" into "the build is red." Once the boundary is mechanical, the payoffs compound — you can swap providers by config, unit-test the core with no network or cloud credentials, and onboard people without explaining unwritten rules. The cost of skipping it is silent coupling: the day you need to change the database or LLM vendor, you discover the "isolated" core imports it in fourteen places, and there is no test to tell you when you've finished untangling it.
On the project this was distilled from — a human-in-the-loop AI agent validated live on a cloud platform then reclaimed via Terraform — the boundary lived in a single import-linter config (.importlinter). One layers contract declared driving > adapters > application > domain; one forbidden contract listed the SDKs banned from the domain (an agent framework, httpx, pydantic, yaml); and a third forbade config and telemetry from importing any outer layer. The check ran inside the project's make check: lint lint-imports test, so a stray import failed CI like a broken test.
Every external collaborator was a Protocol. When a semantic retriever was added later, it shipped as a RetrieverPort Protocol (search(terms, top_k) -> list[PageRef]) — "kept a Protocol like every other collaborator so the application layer depends on a signature, never on the concrete adapter." And because the LLM sat behind a port, development ran against a free local model and later moved to the cloud provider as "a one-line configuration change via the LLM_PROVIDER factory — no application- or domain-layer code touched." Replace the specific library names with your own stack and the structure transfers unchanged.
The contract need not be code imports. The same move applies to a docs or spec artifact: its contract is a schema + structural-integrity rule — every file carries the required frontmatter, an index lists exactly the files that exist on disk, every cross-link resolves — enforced by a commit hook so a broken invariant fails like a red build rather than slipping past a tired reviewer. This pack ships that as a reference implementation: templates/git-controls/ holds a .pre-commit-config.yaml plus zero-dependency POSIX-sh validators that assert its own frontmatter shape, index-vs-directory parity, and link resolution on every commit — the identical "let a machine fail the build, not a human notice" pattern, applied to prose.
Any/untyped so the application secretly depends on the implementation, with no conformance test to catch it.What a machine can check: everything that matters. An import-linter / ArchUnit / dependency-cruiser contract that fails the build the moment domain code imports an adapter or a vendor SDK — running in CI, fail-closed: a missing, empty, or skipped contract is a FAIL, not a pass. The boundary either has a machine on it or it does not exist; a reviewer's eye is defense-in-depth, never the seam.
Related skills: