From dev-agents
Template and conventions for documenting architectural decisions.
How this skill is triggered — by the user, by Claude, or both
Slash command
/dev-agents:adr-formatThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Template and conventions for documenting architectural decisions.
Template and conventions for documenting architectural decisions.
docs/adr/
ADR-001-<slug>.md
ADR-002-<slug>.md
...
Numbering is sequential and never reused. Deprecated ADRs are marked as such, not deleted.
# ADR-NNN: Title
**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-NNN
**Deciders:** [who was involved in this decision]
---
## Context
What is the problem or situation that forced this decision?
What constraints exist (technical, time, team, cost)?
What happens if we do nothing?
## Decision
State the decision clearly in one or two sentences.
Use active voice: "We will..." not "It was decided that..."
## Options Considered
### Option A — [Name]
**Description:** brief explanation
**Pros:** what this gets right
**Cons:** what this gets wrong or costs
### Option B — [Name]
**Description:** brief explanation
**Pros:**
**Cons:**
### Option C — [Name] *(if applicable)*
## Rationale
Why was Option X chosen over the others?
What was the deciding factor?
## Consequences
**Positive:**
- What becomes easier or better
**Negative:**
- What becomes harder or more costly
- What technical debt this introduces
**Actions Required:**
- [ ] Concrete next steps that must happen as a result of this decision
---
*Supersedes: ADR-NNN (if applicable)*
*Related: ADR-NNN (if applicable)*
# ADR-001: Use Promtail instead of Filebeat for log shipping
**Date:** 2024-11-15
**Status:** Accepted
**Deciders:** [you]
---
## Context
We need to ship logs from Nginx, PHP-FPM, and Node.js apps to Loki.
Both Filebeat and Promtail are viable. We already run Grafana and Loki.
## Decision
We will use Promtail for log collection and shipping to Loki.
## Options Considered
### Option A — Promtail
**Pros:** Native Loki integration, label-based pipeline, same ecosystem as Grafana/Loki, lighter resource footprint
**Cons:** Only works with Loki (no Elasticsearch option later without replacing it)
### Option B — Filebeat
**Pros:** More mature, supports multiple outputs
**Cons:** Heavier, requires extra transformation config to work well with Loki, different ecosystem
## Rationale
We are committed to the Grafana/Loki stack. Promtail's native integration reduces config complexity.
The Loki lock-in is acceptable — switching log backends is a deliberate migration, not an accident.
## Consequences
**Positive:** Simpler pipeline config, consistent label model across metrics and logs
**Negative:** Locked to Loki as the log backend
**Actions Required:**
- [ ] Write Promtail scrape configs for all log paths
- [ ] Validate log pipeline end-to-end before decommissioning any existing log collection
npx claudepluginhub tiagokrebs/claude-agentic-platform --plugin dev-agentsWrite an Architecture Decision Record — document what was decided, why, what alternatives were considered, and what trade-offs were accepted. Use when asked to "write an ADR", "document this decision", or "why did we choose X".
Writes Architecture Decision Records (ADRs) documenting decisions, rationale, alternatives, and trade-offs from codebases or conversations. Triggers on 'write an ADR' or 'document decision'.
Document architectural decisions using ADR format. Use when making significant architectural choices that affect future development.