- Home
- Skills
- Code Quality & Review
- Architecture Seam Design
Works with the AI Agents you already use
Architecture Seam Design
Design a stable module or service seam by mapping ownership, comparing boundary options, and specifying contracts, dependency direction, migration, and open risks.
$17
Architecture Seam Design
Example session with this skill installed
Our OrderService directly reads and writes Stripe and the orders table. Design the seam so we can swap payment providers later and keep order logic testable. Compare at least two options.
- Read your context and instructions
- Compiled the architecture seam design
Illustrative worked example. Synthetic scenario from the package; this is not an observed external execution.
PRESSURE
Payment-provider logic is entangled with order persistence. Order rules cannot be tested without live Stripe, and swapping providers would require editing order code.
CURRENT COUPLING
OrderService imports the Stripe SDK and the orders data access object directly.
SELECTED SEAM
Create a PaymentGateway interface owned by a payments module. The interface exposes charge, refund, and verifyWebhook operations. OrderService depends on the interface, not on Stripe.
OWNER / INVARIANTS
The payments module owns provider details and idempotency. OrderService owns order state transitions.
PUBLIC CONTRACT
PaymentGateway provides charge(amount, idempotencyKey) -> Result, refund(id), and verifyWebhook(signature, body).
DEPENDENCY DIRECTION
The orders module depends on the payments interface. The Stripe adapter implements that interface. The orders module never imports Stripe.
MIGRATION
- Define the interface and Stripe adapter.
- Inject the gateway into OrderService.
- Move webhook verification behind the adapter.
- Remove direct Stripe imports from the orders module.
REJECTED ALTERNATIVES
A generic PaymentProviderFactory for three hypothetical providers was rejected because there is no current pressure for that abstraction and it would add cost before the boundary is needed.
OPEN RISKS
Webhook signature handling must remain provider-specific inside the adapter. This remains UNVERIFIED until the adapter is implemented and checked against the project contract.
Connects securely to your tools. The creator never sees your data.
About this skill
When a module or service boundary is hard to change, Architecture Seam Design turns the decision into a bounded, evidence-led design. It names the pressure, maps ownership and invariants, compares at least two materially different seam options, and specifies a smallest stable boundary with a public contract, dependency direction, migration sequence, rejected alternatives, and open risks.
What it does
The workflow reads the smallest sufficient architecture or ADR/spec, callers or consumers, current module boundaries, friction evidence, and tests that encode the public contract. Project governance and committed contracts remain authoritative.
How it works
- Name the pressure and why the change is hard today.
- Map policy, invariants, state ownership, replaceable infrastructure, consumers, and failure boundaries.
- Generate at least two materially different seam options and compare change locality, dependency direction, contract size, migration cost, testability, and failure containment.
- Select and specify the boundary, including allowed dependencies, forbidden knowledge leakage, adapter points, migration sequence, and acceptance evidence.
Output
The result follows a fixed decision shape:
- PRESSURE
- CURRENT COUPLING
- SELECTED SEAM
- OWNER / INVARIANTS
- PUBLIC CONTRACT
- DEPENDENCY DIRECTION
- MIGRATION
- REJECTED ALTERNATIVES
- OPEN RISKS
Boundaries
This is a read-only design phase. It does not reorganize code, commit, push, deploy, install dependencies, or silently expand into implementation. It preserves project authority, separates facts from inferences, and marks unresolved topology UNVERIFIED. It is for a boundary decision, not a localized implementation whose seam is already dictated or read-only debt discovery.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Code Quality & Review.
This is a design and decision workflow, not an implementation. It does not reorganize code, commit, push, deploy, install dependencies, or validate a seam against a running system. It does not replace project governance, ADRs, tests, or implementation review. If required evidence is unavailable, it records the gap as UNVERIFIED rather than inferring topology. It is not for a localized implementation whose seam is already dictated or for read-only debt discovery.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 19 days ago
Permissions
Requires read access to the smallest sufficient project and architecture evidence. The design phase is read-only and does not require shell commands, browser access, network access, MCP services, environment variables, or file writes. If graph tooling is absent, use direct inspection and mark unresolved topology UNVERIFIED.