Skip to main content
skill CX Codex

ports-and-adapters — Claude Code skill: what it does, how to install

ports-and-adapters guides Claude Code in setting up Hexagonal Architecture in Symfony, isolating domain models from Doctrine, HTTP, and vendor SDKs.

MIT ★ 234 updated 2026-10-05

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dev-toolings/superpowers-symfony --skill ports-and-adapters -a claude-code
Open on GitHub

What ports-and-adapters does

This skill organizes Symfony code into Domain, Application, and Infrastructure layers. It models entities and value objects in plain PHP without ORM attributes. Ports sit in the domain as interfaces, while use cases rely on commands and handlers that talk solely to those ports.

Infrastructure handles adapters like Doctrine repositories and API clients, mapping entities externally with XML. Controllers stay in infrastructure, and service configurations bind ports to concrete adapters.

Applying these layers to a basic CRUD module without business logic adds pointless overhead. Domain tests run as plain unit tests without booting the Symfony kernel.

What it helps with

  • isolate core domain logic from Symfony and Doctrine dependencies
  • define port interfaces and bind them to infrastructure adapters
  • configure XML entity mappings outside the domain layer
  • write fast domain unit tests that avoid booting the framework kernel

Example prompts for the agent

  • Structure the billing module into Domain, Application, and Infrastructure layers
  • Define a repository port for customer accounts and set up its Doctrine adapter with XML mapping
  • Implement an order placement use case using a command handler isolated from vendor SDKs

How to install ports-and-adapters

1Skills CLI (Vercel)

npx skills add dev-toolings/superpowers-symfony --skill ports-and-adapters -a claude-code

2Manually: put the files in place

~/.claude/skills/ports-and-adapters/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ports-and-adapters/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ports-and-adapters

How to install ports-and-adapters in Claude Code?

Run npx skills add dev-toolings/superpowers-symfony --skill ports-and-adapters -a claude-code in your terminal.

What does the ports-and-adapters skill do?

It enforces Hexagonal Architecture rules in Symfony projects, keeping src/Domain/ clean of framework imports.

How does it handle entity persistence without ORM attributes?

Entities stay free of Doctrine annotations or attributes, using external XML mappings inside the infrastructure layer instead.

Source text

SKILL.md · MIT
---
name: ports-and-adapters
description: Implement Hexagonal Architecture (Ports and Adapters) in Symfony; separate domain logic from infrastructure with clear boundaries
capabilities: [read, search]
tags: [architecture]
# projected by `bun run build` — do not edit by hand
allowed-tools:
  - Read
  - Glob
  - Grep
---

# Ports And Adapters (Symfony)

## Use when
- Domain rules must not depend on Doctrine, HTTP, or a vendor SDK.
- An infrastructure dependency (storage, payment, mail provider) must be swappable or faked.
- Structuring a bounded context into Domain, Application and Infrastructure layers.

## Default workflow
1. Model the domain in plain PHP: entities and value objects without ORM attributes.
2. Declare ports as interfaces inside the domain, such as a repository interface.
3. Write use cases in the application layer as commands and handlers that depend only on ports.
4. Implement adapters in infrastructure (Doctrine repository, API client) and map entities outside the domain, with XML mapping.
5. Bind each port to its adapter in the service configuration; controllers live in infrastructure.

## Guardrails
- Nothing under `src/Domain/` imports Symfony, Doctrine or vendor SDK classes.
- Dependencies point inward: infrastructure knows the domain, never the reverse.
- Do not add the layers to a CRUD module with no business rules.
- Test the domain with plain unit tests and the adapters with integration tests.

## Progressive disclosure
- Use this file for execution posture and risk controls.
- Open references when deep implementation details are needed.

## Output contract
- The layer layout and the port interfaces.
- The adapters and their service bindings.
- Domain unit tests that boot no kernel.

## References
- `reference.md`

© dev-toolings · MIT · dev-toolings/superpowers-symfony

Similar skills

All skills for Backend and APIs →

From the same set51

The whole set →
twig-components twig-components turns repeated Twig markup into Symfony UX components with props, slots and CVA variants. Handy once the same template chunk starts getting copied around. CX Codex +1 ★ 234repo stars cqrs-and-handlers cqrs-and-handlers implements CQRS in Symfony projects using separate Messenger buses for commands and queries. CX Codex +1 ★ 234repo stars daily-workflow The daily-workflow skill lays out a routine for Symfony work, from getting a project running to checking changes before a commit. Use it for migrations, debugging, and recurring maintenance. CX Codex +1 ★ 234repo stars bootstrap-check bootstrap-check runs a pass/fail check over a Symfony project's setup: .env, services, Doctrine mappings, routes. Each failure comes with the fix. CX Codex +1 ★ 234repo stars config-env-parameters The config-env-parameters skill guides changes to Symfony environment variables, parameters, and secrets across environments. Use it when configuration needs a clear home and safe injection into the app. CX Codex +1 ★ 234repo stars doctrine-fixtures-foundry doctrine-fixtures-foundry teaches the agent to build Doctrine test data with Zenstruck Foundry v2 factories: named states, sequences and entity relations. Triggers when you write fixtures or migrate factories from Foundry v1. CX Codex +1 ★ 234repo stars doctrine-transactions doctrine-transactions guides Claude Code on managing Doctrine ORM 3 transactions, locking strategies, and flush boundaries in Symfony applications. Fits concurrent row edits and rollback recovery. CX Codex +1 ★ 234repo stars doctrine-batch-processing doctrine-batch-processing is a Claude Code skill for processing large Doctrine datasets in memory-conscious imports, exports, and backfills. CX Codex +1 ★ 234repo stars

Project sponsors

Companies that keep this analytics open