design-patterns
Use when choosing or applying a proven architecture pattern for a project built on Effect v4 / the @effected kit — splitting a tool into cli + mcp + lsp packages, deciding how a monorepo ships its bins, making "install one package" true for a consumer, a Claude Code or Copilot plugin launching a project's own bins, or threading one version identity through several front ends. This skill indexes patterns as loadable references; consult it before inventing an architecture the kit's own consumers have already worked out.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 8
- Forks
- 2
01 前言 Front Matter
- name
- design-patterns
- description
- Use when choosing or applying a proven architecture pattern for a project built on Effect v4 / the @effected kit — splitting a tool into cli + mcp + lsp packages, deciding how a monorepo ships its bins, making "install one package" true for a consumer, a Claude Code or Copilot plugin launching a project's own bins, or threading one version identity through several front ends. This skill indexes patterns as loadable references; consult it before inventing an architecture the kit's own consumers have already worked out.
- when_to_use
- carrier package, meta-package, one package to install, bins missing from node_modules/.bin, cli + mcp + lsp split, front end vs engine, keeping the package graph acyclic, plugin loader script, version threading, distribution, engine_version, manifest DAG test, packed-install e2e, tool closure, pin kit dependencies exactly, workspace:* vs workspace:^ for a tool, tool on an older kit release, two copies of a kit package, does not provide an export named, breaking peer floor
02 资源文件 8
- 参考文档references/carrier-app-and-schemas.md14.5 KB
- 参考文档references/carrier-case-studies.md10.8 KB
- 参考文档references/carrier-closure.md5.2 KB
- 参考文档references/carrier-entry-contract.md10.2 KB
- 参考文档references/carrier-package.md7.7 KB
- 参考文档references/carrier-plugin-loader.md9.0 KB
- 参考文档references/carrier-verification.md26.0 KB
- 参考文档references/carrier-version-threading.md7.8 KB
03 SKILL.md 正文
Design patterns
Proven architecture patterns for building on Effect v4 and the @effected
kit, distilled from real multi-package tools and indexed as loadable
references. This skill routes; depth lives in references/.
Pattern index
| Pattern | Reach for it when | Reference |
|---|---|---|
| Carrier package — core/engine/front ends → carrier | a tool ships more than one bin (CLI, MCP server, LSP server, …) and you want "install one package" to be true, or you're debugging why a consumer's node_modules/.bin is missing a bin that resolves fine as a dependency |
carrier-package.md, carrier-entry-contract.md, carrier-version-threading.md, carrier-plugin-loader.md, carrier-verification.md, carrier-closure.md, carrier-app-and-schemas.md (optional), carrier-case-studies.md |
More rows land here as more patterns are distilled. A pattern earns a row once it has shipped in more than one real tool and the trade-offs are settled, not on first use.
Kit exports
The carrier pattern's references teach the shape; where a piece of that shape has shipped as a kit export, reach for the export instead of hand-rolling the recipe again.
| construct | import | reach for it when |
|---|---|---|
CurrentDistribution, DistributionField, distributionSuffix |
@effected/kit |
threading which meta-package a front end was installed through |
LaunchContext |
@effected/kit |
resolving an agent-launched project directory from argv/env/cwd |
CliRuntime.main |
@effected/cli-kit |
assembling a CLI front end's main.ts |
McpStdio |
@effected/mcp-kit |
assembling an MCP front end's main.ts — launch, stdio boundary, teardown |
ProcessGuard, McpGuard |
@effected/kit/guard, @effected/mcp-kit/guard |
crash guards in a server front end's main.ts before its graph loads — any transport (an LSP), or MCP with the launch built in |
WorkspaceLayering, LayerPolicy |
@effected/workspaces/testing |
the manifest DAG test that holds the package graph to a committed policy |
SourceBoundary |
@effected/workspaces/testing |
a package's own process/import boundary test |
PackedInstall |
@effected/workspaces/testing |
the cross-package-manager packed-install e2e |
McpProbe |
@effected/mcp-kit/testing |
the MCP half of a packed-install proof |
Standards
- Name the layer, not the file. "Front end", "engine", "carrier" are roles a package plays, not folder names — a repo may fold a role into an existing package (the carrier as a library) as long as the edges still point one way.
- Keep every edge pointing down. A pattern that needs a same-layer or upward edge to work is the wrong shape for the problem, not a reason to add an exception.
- Verify a pattern against a real tool before applying it, the same evidence discipline as any other platform claim — a pattern description is a distillation, not a substitute for reading the case study it came from.
- Prefer adding a package over introducing a back-edge. Smaller, focused packages composed acyclically have proven more reliable than a shared package importing "up" for convenience.
Footguns
- Bin-linking is direct-dependency-only in every package manager — see carrier-package.md for why hoisting and hand-rolled hoist patterns don't fix it.
- A carrier's front ends belong in
dependencies, neverpeerDependencies— see carrier-package.md. - A tool package that takes the kit at caret ranges changes under its own version and can bind a kit peer across its closure; pin every kit dependency of a tool package exactly — see carrier-closure.md.
- An MCP
main.tsthat imports its server graph statically runs that graph before its crash guards exist: Node prints the throw and exits1on its own, but the server's own handler never runs —McpStdio.launchdoes not remove this requirement, it sits around it — see carrier-entry-contract.md andeffect-v4-mcp'sserver-wiring.md#crash-guards. - A package.json read for "my own version" reports the wrong package's
version once code moves to a shared engine —
CurrentDistributionfixes the identity-threading half of this, not the build-time-literal half — see carrier-version-threading.md. - A plugin loader that dispatches through
pnpm exec/bunx/npm execresolves bins differently per package manager — see carrier-plugin-loader.md. - A manifest DAG test with no positive-control fixture can pass while
checking nothing —
WorkspaceLayering's ownedgeCountguard is that control; a hand-rolledLAYER_RANKStable has to add it itself — see carrier-verification.md.
Additional resources
- references/carrier-package.md — the
problem the carrier pattern solves, its roles and edge direction, the
carrier-as-library deviation, the dependencies-vs-peers rule, and the
release model. Load when: deciding whether a multi-bin tool needs this
shape at all, or reviewing a package's
dependenciesvspeerDependenciessplit. - references/carrier-entry-contract.md
— the four-file front-end contract (
bin.ts/main.ts/index.ts/version.ts), the carrier's bin shims, who declares a bin (carrier-only, recommended; or shared, at the cost of provenance), and the MCP crash-guard requirement. Load when: scaffolding a new front-end package or a carrier's bin shims. - references/carrier-version-threading.md
— build-time version literals, the
DistributionContext.Reference,engine_versionas the comparable version, and the--versionformat. Load when: a tool needs to report which meta-package it was installed through, or two front ends disagree about "the version." - references/carrier-plugin-loader.md
— the Claude Code / Copilot plugin loader shape (
node_modules/.binfirst, install hint, major-pinnednpx -pfallback through the carrier) and the hook CLI resolution order. Load when: writing or reviewing a plugin'smcpServers/lspServersloader script or a hook that shells out to a project's own CLI. - references/carrier-verification.md — the manifest DAG test with non-vacuity, source boundary tests, and the packed-install e2e across package managers. Load when: adding the repo-shape checks to a multi-package tool — uses the kit's checks, not copied tests.
- references/carrier-closure.md — a
tool owns its dependency closure: exact kit pins on every tool package,
why a library keeps carets and peers instead, what pinning does not seal,
and the breaking-floor rule for a library's own releases. Load when:
choosing
workspace:*orworkspace:^(or exact or caret) for a tool package, a tool breaks beside a repository on a newer kit release, or a library release moves a peer floor. - references/carrier-app-and-schemas.md
— the OPTIONAL extension: where the app layer (platform + config
discovery) and a published config-file JSON Schema belong — core owns
shape/version/hosted identity, the engine owns platform + discovery,
front ends only pass in process-derived inputs. Load when: the tool has
a user config file a person hand-edits, or publishes a JSON Schema for
it — cross-links
building-schemastore-schemasfor the generation and drift-gate mechanics rather than re-teaching them here. - references/carrier-case-studies.md — okfit, vitest-agent and systems: what each does best, what each is missing, and the deviations each made and why. Load when: you want a worked, citable example instead of the prescriptive rule alone.
Related skills
effect-v4-cliandeffect-v4-mcpown each front end's own depth — assemblingmain.ts, exit codes, protocol wiring, tool definitions and testing. This skill teaches the shape a multi-front-end tool takes; the two front-end skills teach what happens inside each front end. Knowledge stays split rather than duplicated across all three.
04 同仓库更多 Skills
testing-actions
Use when writing or reviewing tests for @effected/github-actions, @effected/github, @effected/sbom or @effected/commands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre/main/post lifecycle through Action.run, or debugging why a test hits the real network or hangs.
supply-chain-attestation
Use when generating a CycloneDX SBOM, checking NTIA minimum elements, building an in-toto statement or a SLSA provenance predicate, signing into a Sigstore DSSE bundle, or uploading an attestation to GitHub.
structuring-an-action
Use when laying out a new GitHub Action repository on the @effected suite, deciding where a piece of code belongs (an entry point, a step, a shared service, a shim), or reviewing an existing action's file structure against the canonical shape.
running-commands-and-tools
Use when running a subprocess in Effect v4, spawning a command, capturing stdout/stderr/exit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.
release-and-publish
Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.
hardening-a-parser-port
Use when porting or writing a recursive-descent parser, lexer, or tree-walker over untrusted text in the @effected monorepo — the class of hardening the cloud reviewer scans for on every migration. Covers stack-overflow depth guards (on EVERY recursion surface, which a facade has N of — not two), numeric bound guards that must reject NaN and non-integers, code-point range checks scoped to formats with wide escapes, prototype-pollution, control-character rejection, and the invariant that malformed input must fail through the typed error channel, never as an unhandled defect.