AGENT SKILL

record-architecture-decisions

Record small Architecture Decision Records (ADRs) for durable technical choices in this monorepo. Use when a change chooses among meaningful alternatives, moves from an ideal approach to a practical one because of discovered constraints, establishes a cross-component contract or convention, accepts a consequential trade-off, or supersedes an earlier decision. Also use before completing any non-trivial implementation thread or merge request to decide whether its work produced an ADR-worthy decision.

License 许可
MIT
最近更新
2026-10-21
Stars
★ 0
Forks
0

01 前言 Front Matter

name
record-architecture-decisions
description
Record small Architecture Decision Records (ADRs) for durable technical choices in this monorepo. Use when a change chooses among meaningful alternatives, moves from an ideal approach to a practical one because of discovered constraints, establishes a cross-component contract or convention, accepts a consequential trade-off, or supersedes an earlier decision. Also use before completing any non-trivial implementation thread or merge request to decide whether its work produced an ADR-worthy decision.

02 资源文件 2

03 SKILL.md 正文

Record Architecture Decisions

Capture why a decision made sense with the constraints and evidence available at the time. Keep the record useful after those constraints change.

Evaluate the change

  1. Review the conversation, implementation attempts, test results, and diff for durable decisions.
  2. Write an ADR when the work:
    • chose among meaningful alternatives;
    • abandoned a preferred design because evidence exposed a constraint;
    • established a convention, dependency, interface, data model, deployment pattern, or operational policy;
    • accepted a trade-off that a future maintainer may otherwise undo without understanding it; or
    • changes a decision documented by an existing ADR.
  3. Skip an ADR for routine maintenance, implementation details, straightforward bug fixes, and choices already dictated by an accepted ADR.
  4. If no ADR is needed, state that explicitly in the final handoff.

Write the ADR

  1. Read docs/adr/README.md and docs/adr/template.md completely.
  2. Create docs/adr/YYYY-MM-DD-short-title.md. Use a specific, durable title and avoid sequential numbers that conflict across concurrent branches.
  3. Preserve the facts from the work:
    • the need or problem;
    • the constraints encountered;
    • concrete evidence such as failed approaches, validation results, limits, or links;
    • the chosen approach and meaningful rejected alternatives;
    • positive and negative consequences; and
    • conditions under which the decision should be reconsidered.
  4. Keep the ADR terse and scannable:
    • Default to one or two concise bullets under each template heading.
    • Use paragraphs only when bullets would obscure necessary reasoning.
    • Combine closely related alternatives and consequences instead of cataloging every detail.
    • Preserve the decision, evidence, trade-off, and reconsideration trigger without narrating the implementation.
  5. Include the ADR in the same merge request as the decision whenever possible.

Preserve history

  • Do not rewrite a landed ADR to make the old decision appear current.
  • Add a new ADR when a decision changes, and link the earlier record under Supersedes.
  • Do not add approval or status metadata. Landing through merge request review records acceptance; an unmerged ADR remains a proposal in its branch.

04 同仓库更多 Skills

fern-works
fern-works/greenline

use-garden

Consulting garden, the separately installed guidance command this repository's owner enabled, when an open engineering choice the repository does not settle, made in a change or only recommended, would be informed by published guidance. Use for a choice between approaches, a pattern or pitfall for a technology or concern the work touches, or a unit a repository decision names; not for a question about this repository's own facts or a change whose choices are already settled.

★ 0
fern-works
fern-works/greenline

use-garden

Consulting garden, the separately installed guidance command this repository's owner enabled, when an open engineering choice the repository does not settle, made in a change or only recommended, would be informed by published guidance. Use for a choice between approaches, a pattern or pitfall for a technology or concern the work touches, or a unit a repository decision names; not for a question about this repository's own facts or a change whose choices are already settled.

★ 0
fern-works
fern-works/greenline

what-to-build

Propose what this product could do next at three altitudes: sharpen a shipped slice, extend one, or open ground the product does not stand on yet. Use for 'what should we build next', 'any ideas for this app', 'what's missing', 'is this done or is there more in it', and quick-win hunts. Not for refactors, which belong to the architecture survey.

★ 0
fern-works
fern-works/greenline

wayfinder

Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets in a plan directory's map.md, and resolve them one at a time until the way to the destination is clear.

★ 0
fern-works
fern-works/greenline

verify

Prove a change's claims with fresh evidence: restate each item of its acceptance so it can fail, capture a baseline and a treatment with the same command, compare the raw artifacts, and return VERIFIED, NOT VERIFIED or INCONCLUSIVE for each, at the depth the change's mode gives the verify step. Use when the mode reaches verify, or when the owner says "verify this", "prove it works" or "did this fix it".

★ 0
fern-works
fern-works/greenline

tdd

Test-first development at any step: discover the repository's own test commands, name the break a test catches, watch it fail for the intended reason, make it pass with the smallest change, and add a new test only where it catches a realistic failure the existing ones would miss. Use when writing or changing a test, building a feature or fixing a bug test-first, or deciding whether a change needs a new test; also on 'red-green-refactor' and integration tests.

★ 0