| name | respecting-adrs |
| description | Use whenever you are about to propose a technical solution, write code, or implement a feature. Ensures the proposal respects the project's accepted ADRs before writing a single line of code. Auto-activates when detecting context like "implement X", "how do I Y", "I'm going to use library Z", or similar. |
Respecting ADRs before coding
ADRs (docs/decisions/ADR-*.md) are the project's structural decisions with status accepted. Every technical proposal must respect them — a violation requires opening a new superseding ADR, not bypassing them.
When this skill activates
Auto-activates when the context involves:
- "Implement X"
- "I'm going to write / code / create"
- "Which library to use"
- "How do I Y in [language/framework]"
- "Refactor to use Z"
- Proposing a diff/PR
Procedure (4 steps)
Step 1 — List the relevant accepted ADRs
Run this mentally: "Which ADRs in this project might have something to say about what I'm about to do?"
- Always consult
docs/decisions/README.md (the index).
- If the proposal touches: database → ADR about persistence; auth → ADR about auth; external libraries → ADR about the stack; etc.
- If there is no ADR on the topic but the decision is structural → open an ADR first (
/adr).
Step 2 — Validate the proposal against each identified ADR
For each relevant ADR:
- Read the "Decision" and "Enforcement" sections.
- Confirm that the proposal does not contradict the decision.
- If the ADR has a hook (
.claude/rules.yaml), make sure your code won't be blocked by it.
Step 3 — If there's a conflict, STOP
Don't code. Options:
- Refine the proposal to respect the ADR (most common).
- Open a new ADR superseding the old one, if the old decision really is wrong (use
/adr).
- Ask the user for clarification if the conflict isn't clear.
NEVER work around the hook or use a silent workaround.
Step 4 — Cite the ADR in the commit/PR
When implementing, mention the relevant ADR:
feat(providers): ClienteRepo em providers/impl (ADR-007 adapter pattern)
Examples
✅ Good
User: "I'm going to add a cache lib to the worker to store responses."
Skill activates: "Before coding, I'll consult the ADRs. ADR-004 defines technology X for path A, OK. But this cache is a different kind (key-value) and ADR-004 doesn't cover that use. I'll reuse the same infrastructure already available with a dedicated prefix. It doesn't violate ADR-004 or create a new structural decision (caching is an implementation detail)."
❌ Bad
User: "I'm going to add a second database to persist sessions."
Skill does NOT activate, or activates but is ignored: "I added the driver and created the sessions table..."
Result: violates ADR-006 (that database is OUT of scope for the current phase). The hook won't block it (there's no rule), but a structural decision was made without an ADR. Technical debt created.
❌ Worse
User: "I need to use library Z for a specific case."
Skill activates: "ADR-002 explicitly forbids library Z. The hook will block it. I'll use it anyway and add a # noqa on the import."
NO. If you really need it, open ADR-009 superseding ADR-002 with concrete justification. Otherwise, rework the proposal.
Anti-patterns of this skill
- ❌ "I already know this ADR doesn't apply" without reading — always read.
- ❌ Citing an ADR in the commit but not having actually validated it.
- ❌ Skipping Step 1 ("obviously it complies") — it's not obvious until confirmed.
