Help us improve
Share bugs, ideas, or general feedback.
From acc
Generates Architecture Decision Records (ADRs) for PHP projects using standard Markdown template with context, decision, consequences (positive/negative/risks), alternatives, and references.
npx claudepluginhub dykyi-roman/awesome-claude-code --plugin accHow this skill is triggered — by the user, by Claude, or both
Slash command
/acc:adr-templateThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Generate Architecture Decision Records following the standard format.
Creates Architecture Decision Records (ADRs) with title, status, and MADR/basic/extended templates. Auto-numbers sequentially, prompts for context/options/rationale, writes to docs/decisions/ or docs/adr/.
Generates Architectural Decision Records (ADRs) in MADR, Nygard, Alexandrian, or project formats. Researches directory for conventions, gathers context, numbers sequentially, validates, and saves. Use for documenting technical decisions.
Generates Architecture Decision Records (ADRs) capturing context, rationale, alternatives, and consequences in numbered status-tracked Markdown format. Useful for documenting architectural decisions with lifecycle management.
Share bugs, ideas, or general feedback.
Generate Architecture Decision Records following the standard format.
# ADR-{number}: {Title}
**Status:** {Proposed | Accepted | Deprecated | Superseded}
**Date:** {YYYY-MM-DD}
**Deciders:** {names or roles}
## Context
{What is the issue that we're seeing that motivates this decision?}
## Decision
{What is the change that we're proposing/doing?}
## Consequences
### Positive
{What becomes easier?}
### Negative
{What becomes harder?}
### Risks
{What could go wrong?}
## Alternatives Considered
{What other options were evaluated?}
## References
{Links to relevant resources}
# ADR-001: Use Domain-Driven Design Architecture
Format: "ADR-{NNN}: {Verb} {Noun/Concept}"
Good:
- Use Domain-Driven Design
- Implement CQRS Pattern
- Adopt PostgreSQL for Primary Storage
- Separate Read and Write Models
Bad:
- DDD (too short)
- Architecture Decision (too vague)
- We should use DDD (conversational)
**Proposed** — Under discussion, not yet decided
**Accepted** — Decided and implemented
**Deprecated** — No longer recommended
**Superseded by ADR-XXX** — Replaced by newer decision
## Context
Describe the situation that led to this decision:
- What problem are we solving?
- What forces are at play?
- What constraints exist?
- What is the current state?
Example:
---
The system has grown to 50+ controllers with business logic scattered
across controllers, services, and repositories. This leads to:
- Code duplication across features
- Difficulty testing business rules
- Unclear ownership of business logic
- Tight coupling to Symfony framework
We need a clear structure to organize business logic.
## Decision
State the decision clearly:
- Use active voice
- Be specific about what changes
- Include key implementation details
Example:
---
We will adopt Domain-Driven Design (DDD) with the following structure:
1. **Domain Layer** — Contains entities, value objects, domain events,
and repository interfaces. No framework dependencies.
2. **Application Layer** — Contains use cases that orchestrate domain
objects. Defines DTOs for input/output.
3. **Infrastructure Layer** — Implements repository interfaces,
integrates with database, cache, and external services.
4. **Presentation Layer** — Handles HTTP requests/responses using
ADR pattern (Action-Domain-Responder).
## Consequences
### Positive
List benefits gained:
- Clearer separation of concerns
- Domain logic independent of framework
- Easier to test business rules
- Better code organization
### Negative
List drawbacks accepted:
- More files and directories
- Learning curve for team
- Initial refactoring effort
- More boilerplate code
### Risks
List potential issues:
- Team may over-engineer simple features
- Boundaries may be drawn incorrectly initially
- Refactoring existing code may introduce bugs
## Alternatives Considered
### Alternative 1: {Name}
**Description:** {What is it?}
**Pros:**
- {benefit 1}
- {benefit 2}
**Cons:**
- {drawback 1}
- {drawback 2}
**Why Rejected:** {reason}
### Alternative 2: {Name}
...
# ADR-003: Use PostgreSQL for Primary Database
**Status:** Accepted
**Date:** 2025-01-15
**Deciders:** Tech Lead, Backend Team
## Context
We need to select a primary database for the new order management system.
Requirements include:
- Support for complex queries on order data
- JSONB storage for flexible product attributes
- Strong ACID compliance for financial transactions
- Good performance at 10K orders/day scale
- Team familiarity and ecosystem support
Current tech stack uses MySQL 5.7 for legacy systems.
## Decision
We will use PostgreSQL 16 as the primary database for the following reasons:
1. **JSONB Support** — Native JSON storage with indexing for product
attributes that vary by category
2. **Advanced Types** — UUID, arrays, enums as native types reduce
application-level validation
3. **Better Query Optimizer** — Handles complex JOINs across order,
item, and inventory tables more efficiently
4. **Extensibility** — PostGIS for future location features,
full-text search without external service
Implementation notes:
- Use Doctrine ORM with PostgreSQL-specific types
- Enable UUID generation at database level
- Configure connection pooling with PgBouncer
## Consequences
### Positive
- Native JSONB eliminates need for EAV pattern
- Better query performance for complex reports
- Strong typing catches data issues early
- Modern features reduce application complexity
### Negative
- Team needs PostgreSQL training (2-3 days)
- Different SQL dialect from MySQL
- Hosting costs slightly higher
- No existing internal DBA expertise
### Risks
- Migration from MySQL may surface data issues
- Performance tuning requires new expertise
- Backup/recovery procedures need updating
## Alternatives Considered
### MySQL 8.0
**Description:** Upgrade existing MySQL infrastructure
**Pros:**
- Team familiarity
- Existing tooling and procedures
- Lower migration effort
**Cons:**
- JSON support less mature than PostgreSQL
- Missing advanced types
- Query optimizer less capable
**Why Rejected:** Long-term technical debt outweighs short-term convenience
### MongoDB
**Description:** Document database for flexibility
**Pros:**
- Schema flexibility
- Native JSON
- Horizontal scaling
**Cons:**
- No ACID for multi-document transactions
- Team has no experience
- Complex queries harder
**Why Rejected:** Financial data requires strong ACID guarantees
## References
- [PostgreSQL vs MySQL Comparison](https://example.com/comparison)
- [PostgreSQL 16 Release Notes](https://www.postgresql.org/docs/16/release-16.html)
- Internal RFC: Database Selection Criteria
docs/adr/
├── 000-adr-template.md # Template file
├── 001-use-ddd.md # First decision
├── 002-implement-cqrs.md # Second decision
├── 003-use-postgresql.md # Third decision
└── README.md # Index of all ADRs
# Architecture Decision Records
## Active Decisions
| ADR | Date | Title | Status |
|-----|------|-------|--------|
| [001](001-use-ddd.md) | 2025-01-10 | Use Domain-Driven Design | Accepted |
| [002](002-implement-cqrs.md) | 2025-01-12 | Implement CQRS Pattern | Accepted |
| [003](003-use-postgresql.md) | 2025-01-15 | Use PostgreSQL | Accepted |
## Deprecated Decisions
| ADR | Date | Title | Superseded By |
|-----|------|-------|---------------|
| [000](000-monolith.md) | 2024-06-01 | Monolith Architecture | ADR-010 |
When generating an ADR: