adr-authoring

Estrelas1

Forks0

Atualizado17 de maio de 2026 às 04:58

Write Architecture Decision Records when making significant technical choices. Use when selecting tools, patterns, frameworks, or making structural changes that future developers need to understand.

Instalação

Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.

Fonte

smileynet

smileynet/agent-crews

Abrir repositório GitHub Ver repositórios do creator

Download

Ocupações relacionadasSOC

Baseado na classificação ocupacional SOC

Desenvolvedores de softwareInformática e Matemática·SOC 15-1252

SKILL.md

readonly

name	adr-authoring
description	Write Architecture Decision Records when making significant technical choices. Use when selecting tools, patterns, frameworks, or making structural changes that future developers need to understand.

ADR Authoring

Record decisions so future-you (and future-teammates) know WHY, not just WHAT.

When to write an ADR

Choosing between competing approaches (framework A vs B)
Adopting a pattern that constrains future work
Rejecting an obvious approach (explain why not)
Changing a previous decision (superseding)

Do NOT write ADRs for: trivial choices, temporary experiments, or decisions that are easily reversed.

Format (MADR-lite)

# ADR-NNNN: [Decision Title]

**Status:** proposed | accepted | deprecated | superseded by ADR-XXXX
**Date:** YYYY-MM-DD
**Deciders:** [who was involved]

## Context

What is the issue? What forces are at play? Why does this decision need to be made now?

## Decision

What did we decide? State it clearly in one sentence, then elaborate.

## Consequences

### Positive
- [What becomes easier or better]

### Negative
- [What becomes harder or what we give up]

### Neutral
- [Side effects that aren't clearly good or bad]

## Alternatives Considered

### [Alternative 1]
- Pros: ...
- Cons: ...
- Why rejected: ...

## References

- [Research artifact that informed this] (link to docs/research/ if applicable)
- [Related ADRs]

Lifecycle

Proposed — written, not yet agreed upon
Accepted — team agrees, implementation proceeds
Deprecated — no longer applies (explain why)
Superseded — replaced by a newer ADR (link to it)

Storage

Path: docs/adrs/NNNN-short-title.md
Number sequentially (0001, 0002, ...)
Keep an index in docs/adrs/README.md or link from project README

Linking to research

If a research artifact (warlock output, BPAPPA survey) informed this decision, link it:

## References
- [Research: JWT vs Session Auth](../research/bpappa-auth-patterns.md) — informed this decision

The research artifact should back-link: Consumed by: ADR-0003

Mais deste repositório

mesmo repositório

agents-md-authoring

smileynet/agent-crews

Write AGENTS.md files that serve as operating contracts for AI agents. Use when creating or updating AGENTS.md for a project. Trigger terms: AGENTS.md, agent instructions, agent contract, agent configuration, coding agent setup.

2026-05-171

changelog-discipline

smileynet/agent-crews

Quality rules for changelog entries. Use when validating, writing, or reviewing changelog content to ensure user-facing value communication.

2026-05-171

completion-protocol

smileynet/agent-crews

Task completion sequence including verification, git, signaling, and handoff. Use when finishing a task or reporting status.

2026-05-171

diagrams

smileynet/agent-crews

Architecture diagrams for documentation. Covers ASCII, Mermaid, C4, and D2. Applies C4 methodology by default. Trigger terms: diagram, flowchart, architecture diagram, sequence diagram, C4, mermaid, ascii diagram.

2026-05-171

diataxis-classification

smileynet/agent-crews

Classify documentation by audience and content type. Use when planning, auditing, or placing project documentation.

2026-05-171

docs-audit

smileynet/agent-crews

Audit project documentation for quality, completeness, and freshness. Use when assessing documentation health, planning cleanup, or measuring improvement.

2026-05-171

ADR Authoring

Record decisions so future-you (and future-teammates) know WHY, not just WHAT.

When to write an ADR

Choosing between competing approaches (framework A vs B)

Adopting a pattern that constrains future work

Rejecting an obvious approach (explain why not)

Changing a previous decision (superseding)

Do NOT write ADRs for: trivial choices, temporary experiments, or decisions that are easily reversed.

Format (MADR-lite)

# ADR-NNNN: [Decision Title] **Status:** proposed | accepted | deprecated | superseded by ADR-XXXX **Date:** YYYY-MM-DD **Deciders:** [who was involved] ## Context What is the issue? What forces are at play? Why does this decision need to be made now? ## Decision What did we decide? State it clearly in one sentence, then elaborate. ## Consequences ### Positive - [What becomes easier or better] ### Negative - [What becomes harder or what we give up] ### Neutral - [Side effects that aren't clearly good or bad] ## Alternatives Considered ### [Alternative 1] - Pros: ... - Cons: ... - Why rejected: ... ## References - [Research artifact that informed this] (link to docs/research/ if applicable) - [Related ADRs]

Lifecycle

Proposed — written, not yet agreed upon

Accepted — team agrees, implementation proceeds

Deprecated — no longer applies (explain why)

Superseded — replaced by a newer ADR (link to it)

Storage

Path: docs/adrs/NNNN-short-title.md

Number sequentially (0001, 0002, ...)

Keep an index in docs/adrs/README.md or link from project README

Linking to research

If a research artifact (warlock output, BPAPPA survey) informed this decision, link it:

## References - [Research: JWT vs Session Auth](../research/bpappa-auth-patterns.md) — informed this decision

The research artifact should back-link: Consumed by: ADR-0003