architecture-patterns

Overview of architecture-patterns skill

What the architecture-patterns skill is for

The architecture-patterns skill helps an agent design or refactor backend code around proven structural patterns such as Clean Architecture, Hexagonal Architecture, Onion Architecture, and Domain-Driven Design. Its real job is not just to name patterns, but to turn a service boundary or messy module into a clearer layering model with dependency rules, interfaces, test seams, and bounded responsibilities.

Best fit for backend teams and refactors

This skill is best for developers working on backend services, internal platforms, or modular monoliths who need a maintainable structure before code volume grows. It is especially useful when business logic is mixed with controllers, ORM models, transport code, or vendor SDKs, and you want a design that is easier to test and evolve.

What users usually want from architecture-patterns

Most users looking at architecture-patterns want one of four outcomes: a clean starting structure for a new service, a safe refactor path for an existing codebase, a better bounded context split before microservices, or a fix for dependency cycles and framework leakage into domain code. This skill is stronger than a generic “design my architecture” prompt because it gives a pattern vocabulary, layer responsibilities, and implementation shape.

Main differentiators

The strongest differentiator in the architecture-patterns skill is that it combines multiple backend architecture styles instead of forcing one template. It also goes beyond high-level concepts by describing concrete layer responsibilities, inward dependency flow, interface boundaries, and DDD tactical elements like aggregates, value objects, and domain events. The included references/advanced-patterns.md adds realistic multi-service structures and cross-context patterns that help with adoption decisions.

When this skill is a poor fit

Skip this skill if you only need a tiny CRUD endpoint, a framework-specific starter, or a front-end component architecture. It is also a weak fit if your main need is infrastructure topology, deployment design, or cloud networking rather than application boundaries and code organization.

How to Use architecture-patterns skill

Install context for architecture-patterns

The upstream skill does not publish its own standalone installer inside SKILL.md; it lives inside the wshobson/agents repository under plugins/backend-development/skills/architecture-patterns. In a skills-enabled environment, users typically add it from the repo, for example:

npx skills add https://github.com/wshobson/agents --skill architecture-patterns

If your agent platform uses a different import flow, point it at the same repository path and verify the skill name matches architecture-patterns.

Read these files before first use

Start with:

• plugins/backend-development/skills/architecture-patterns/SKILL.md
• plugins/backend-development/skills/architecture-patterns/references/advanced-patterns.md

Read SKILL.md first for the core pattern guidance and dependency rules. Read references/advanced-patterns.md when you need richer examples for bounded contexts, anti-corruption layers, or larger service layouts. That second file matters because it helps translate the pattern theory into a repository shape you can actually implement.

What input the skill needs to work well

The architecture-patterns usage quality depends heavily on the boundary definition you provide. Give the agent:

• the service or module purpose
• main domain concepts
• key workflows or use cases
• current pain points
• existing framework and language
• persistence and messaging constraints
• whether you are starting new or refactoring existing code
• any hard boundaries like team ownership, compliance, or latency needs

Without that, the skill may produce a generic layered diagram that sounds right but is not actionable.

Turn a rough goal into a strong architecture-patterns prompt

Weak prompt:

“Use architecture-patterns for my backend.”

Stronger prompt:

“Use architecture-patterns for Backend Development on a Python order service. We are refactoring a Django app where business rules live in models and views. Design bounded contexts, propose Clean or Hexagonal layering, define repository interfaces, identify domain entities and value objects, and show where payment gateway and database adapters should live. We need unit tests for use cases without a database and a migration path that avoids a full rewrite.”

That stronger version improves output because it specifies domain, current failure mode, target pattern decisions, external dependencies, and delivery constraints.

Choose the right pattern instead of forcing one

A practical use of architecture-patterns guide is pattern selection, not blind adoption. In practice:

• Use Clean Architecture when you need strong isolation of business rules from frameworks.
• Use Hexagonal Architecture when ports and adapters are the clearest way to separate external systems.
• Use Onion Architecture when you want a similar inward dependency model with a simple conceptual center.
• Use DDD elements when domain complexity is real and language precision matters.

If your domain is shallow, use the lighter parts only. Over-modeling simple CRUD is a common adoption mistake.

Recommended workflow in an agent session

A good session flow is:

1. Define the business capability or bounded context.
2. Ask the agent to identify domain entities, value objects, aggregates, and use cases.
3. Ask it to map dependencies and separate domain, application, adapters, and infrastructure concerns.
4. Ask for a target folder structure aligned to your language and framework.
5. Ask for interface definitions for repositories, event publishers, or external clients.
6. Ask for a refactor sequence if you already have code.
7. Ask for test boundaries: unit, integration, and adapter tests.

This workflow gets more value from the skill than a one-shot “design everything” request.

What outputs to expect from architecture-patterns usage

Good outputs from the architecture-patterns skill usually include:

• a proposed layer model
• dependency direction rules
• domain and use-case boundaries
• interface or port definitions
• adapter examples
• project structure suggestions
• testing strategy by layer

If you do not get all of these, your prompt was probably too abstract or too broad.

How to use it for refactoring, not just greenfield work

architecture-patterns install is only the first step; most real value comes during refactors. For existing systems, provide a short inventory of current files and coupling problems, then ask the agent to classify each concern into domain, use case, adapter, or infrastructure. This makes the skill actionable because it can produce a migration path instead of a fresh idealized diagram.

Practical prompt template

Use a prompt like this:

“Apply architecture-patterns to this backend module. Context: [service purpose]. Stack: [language/framework]. Current issues: [coupling, test pain, dependency cycles]. Required integrations: [DB, queue, third-party APIs]. Deliverables: proposed architecture style, layer responsibilities, folder structure, interfaces/ports, test strategy, and incremental refactor plan. Prefer decisions that fit our current codebase rather than a rewrite.”

Constraints and tradeoffs to watch

This skill is conceptually strong, but it is not a framework-specific code generator. You may need follow-up prompts to adapt the structure to Spring Boot, NestJS, FastAPI, Rails, or another ecosystem. It also assumes architecture discipline matters enough to justify extra abstraction. If speed of shipping a simple endpoint is your only priority, the recommended structure can feel heavy.

architecture-patterns skill FAQ

Is architecture-patterns good for beginners?

Yes, if you already understand basic backend concepts like controllers, services, repositories, and tests. The skill explains proven patterns clearly enough to guide learning, but complete beginners may still need extra help translating the pattern language into framework-specific code.

Is this better than a normal architecture prompt?

Usually yes. A generic prompt often produces vague advice like “separate concerns” and “use services.” The architecture-patterns skill gives more useful structure: named patterns, dependency direction, domain boundaries, and testable seams. That makes the output easier to implement and critique.

Can I use architecture-patterns for a monolith?

Yes. In fact, it is often more valuable in a modular monolith than in early microservices. You can use bounded contexts and inward dependencies to clean up a monolith before deciding whether service extraction is even necessary.

Does it require Domain-Driven Design?

No. DDD is part of the skill, but not every project needs full tactical modeling. You can use just the layering and port-and-adapter guidance. Bring in aggregates, value objects, and domain events only when domain complexity justifies them.

Is architecture-patterns suitable for framework-heavy stacks?

Yes, but expect adaptation work. The skill is framework-agnostic by design, which is good for clean boundaries but means you should ask explicitly how the pattern maps onto your framework conventions and dependency injection model.

When should I not use architecture-patterns?

Do not use architecture-patterns when the problem is mainly UI architecture, cloud infrastructure layout, or a tiny CRUD feature with little business logic. In those cases, the abstraction cost may outweigh the benefit.

How to Improve architecture-patterns skill

Give the skill sharper boundaries

The fastest way to improve architecture-patterns results is to define the domain boundary more precisely. “Order service” is acceptable; “order placement, payment authorization, inventory reservation, and shipment initiation” is much better. Clear boundaries help the agent choose between entities, use cases, and adapters correctly.

Show the current coupling problems

If you are refactoring, include examples such as:

• controllers containing business rules
• ORM models sending emails
• use cases importing framework classes
• domain logic requiring a live database
• circular imports between application layers

This helps the skill target the right architecture fix instead of returning generic best practices.

Ask for outputs in implementation order

Many users get a polished architecture description but no execution path. Improve that by asking for results in this order:

1. bounded contexts
2. layer responsibilities
3. ports/interfaces
4. folder structure
5. refactor sequence
6. test plan

That order makes the architecture-patterns guide more usable for real delivery work.

Force tradeoff-aware recommendations

Ask the agent to justify why Clean, Hexagonal, Onion, or selective DDD is the best fit for your case. This avoids pattern cargo-culting. A useful prompt addition is: “Prefer the lightest architecture that preserves testability and clear boundaries.”

Use the advanced reference when system scope grows

For larger systems, explicitly ask the agent to consult references/advanced-patterns.md for examples of bounded contexts, anti-corruption layers, and multi-service structures. This is especially important when your service interacts with legacy systems or multiple domains.

Common failure modes in architecture-patterns usage

The most common problems are:

• too little domain context
• asking for a full-system redesign in one pass
• treating every concept as a bounded context
• creating repository interfaces without clear use cases
• pushing framework types into the domain layer
• overusing DDD patterns in simple CRUD areas

These are not flaws in the skill alone; they usually come from low-quality inputs or mismatched scope.

Iterate after the first output

Do not stop at the first architecture draft. Ask follow-ups such as:

• “Which dependencies still violate inward flow?”
• “What can stay simple CRUD instead of full DDD?”
• “Show a migration plan from current files to target layers.”
• “Which interfaces are essential now, and which can wait?”
• “How should tests differ for domain, use case, and adapter layers?”

That second round is often where architecture-patterns for Backend Development becomes implementation-ready.

Pair architecture-patterns with real repository evidence

You will get better results if you paste a small file tree, a few representative classes, or one problematic workflow. The skill is strongest when it can map theory to actual code boundaries. Even 20 to 50 lines of representative code can materially improve the architecture recommendation.