agentdev-decision-guidelines

Evaluates whether architectural changes require a formal Decision record.

Updated Mar 7, 2026
One-click install
npx skills add https://github.com/yogata/agent-dev-flow --skill agentdev-decision-guidelines-yogata
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: agentdev-decision-guidelines
Source: https://github.com/yogata/agent-dev-flow/tree/main/src/opencode/skills/agentdev-decision-guidelines
Command: npx skills add https://github.com/yogata/agent-dev-flow --skill agentdev-decision-guidelines-yogata

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams often struggle to decide which technical changes deserve a formal Architecture Decision Record and which should be handled as ordinary requirement or design updates, leading to either decision-record sprawl or missed documentation of critical choices. ## Core Features & Use Cases - Decision Threshold Evaluation: Applies criteria such as architectural significance, long-term impact, and reversibility cost to judge whether a change warrants a Decision record. - Boundary Rules: Distinguishes Decision-worthy topics from specification changes, workflow definitions, naming conventions, and template updates that belong in REQ/Design/guide documents. - Lifecycle Guidance: Defines Proposed, Accepted, Superseded, and Deprecated states plus rules for immutability and non-semantic corrections of accepted Decisions. - Use Case: When proposing to adopt a new authentication scheme or change a data access pattern, use this Skill to determine whether to draft a new Decision, update an existing one, or handle it as a Design document change. ## Quick Start Ask the agent to evaluate whether your proposed architecture change, such as switching the data access layer to the Repository pattern, requires creating a new Decision record.

Frequently Asked Questions about agentdev-decision-guidelines

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I decide if a change needs an architecture decision record?▼

Evaluate the change against three criteria: architectural significance affecting system structure, long-term impact on future development, and high cost of reversal. If any criterion applies, such as selecting a tech stack or authentication scheme, create a Decision record.

What changes should not become architecture decision records?▼

Specification-only changes, command behavior definitions, workflow definitions, naming conventions, template changes, and non-technical agreements should not become Decisions. Handle these as REQ, Design, or guide document updates instead.

Can I edit an accepted architecture decision record?▼

Accepted Decisions are semantically immutable. Only non-semantic fixes like typos, broken links, or formatting corrections may be edited directly with explicit approval. Semantic changes require creating a new superseding Decision.

What are the lifecycle states of a decision record?▼

Decision records move through Proposed, Accepted, Superseded, and Deprecated states. A Superseded Decision references its successor via a superseded-by field, while Deprecated marks decisions no longer recommended.

When should I update an existing decision instead of creating a new one?▼

Before creating a new Decision, check for content overlap with existing accepted Decisions. If the content duplicates an existing record, update that Decision rather than creating a new one. Deletion or retirement topics use retire/supersede instead.