AGENT SKILL

adr-manager

Document architectural decisions using the Michael Nygard ADR format. Use when a significant architectural choice is made: picking a database, deciding on an API protocol, adopting a new pattern, or choosing between competing approaches.

使用场景后端与接口
License 许可
MIT
所属仓库
muratovv/ai-hats
最近更新
2026-11-05
Stars
★ 3
Forks
1

01 前言 Front Matter

name
adr-manager
license
MIT
description
Document architectural decisions using the Michael Nygard ADR format. Use when a significant architectural choice is made: picking a database, deciding on an API protocol, adopting a new pattern, or choosing between competing approaches.

03 SKILL.md 正文

ADR Manager

Standardize documentation of architectural decisions for traceability.

When to Use

Records a decision already made, for traceability — it is not where you explore options (that is the plan stage) and not general prose docs (→ doc-protocol). The architecture skills whose Completion step appends findings to an ADR (clean-architecture-guide, api-evolution-checklist, distributed-systems-checklist, trust-boundary-mapping) all feed into this format; this skill owns the record, not the analysis behind it.

Format (Michael Nygard)

  • Title: Short noun phrase
  • Context: What is the problem we are solving?
  • Decision: What is the change we are making?
  • Status: Proposed / Accepted / Deprecated / Superseded
  • Consequences: What becomes easier or harder as a result?

Storage

Save all ADRs sequentially in docs/adr/ (e.g., 0001-use-grpc-for-internal-services.md).

Completion

  • ADR file created in docs/adr/ with sequential numbering
  • All 5 sections filled (Title, Context, Decision, Status, Consequences)

Bundled Rules

Architecture Foundation

  1. Context Management: Summarize architectural state into ADRs. Operate at C4 level.
  2. Distributed Systems: Design for failure — retries, circuit breakers, graceful degradation.
  3. API-First: Define contracts before systems (OpenAPI/Protobuf). Strict backward compatibility.
  4. Delegation: Delegate deep dives to sub-agents, synthesize findings into ADR updates.

Anti-Patterns

  • Missing consequences — the most valuable section, forces thinking about trade-offs
  • Documenting after the fact without context — write the ADR when the decision is fresh
  • ADR without status — unclear whether this is a proposal or accepted decision

04 同仓库更多 Skills

muratovv
muratovv/ai-hats

tool-evaluation-protocol

Time-bounded protocol for evaluating new tools, libraries, or methodologies before adoption. Use when evaluating a candidate dependency for the project, researching a methodology (e.g. ML/LLM frameworks, testing approaches), or following up on a hype-driven recommendation.

★ 3
muratovv
muratovv/ai-hats

systematic-debugging

4-phase bug-fix protocol (evidence, pattern, hypothesis, verify). Use when investigating any error, failure, or unexpected behavior, handling bug reports from users or monitoring, or diagnosing test failures with non-obvious causes.

★ 3
muratovv
muratovv/ai-hats

skill-template

Canonical template and validation guide for ai-hats skills. Use when creating a new skill, reviewing an existing one for structural compliance, or deciding which pattern fits a new behavior.

Skill与智能体开发
★ 3
muratovv
muratovv/ai-hats

skill-optimization

Audit and refactor library components to eliminate redundancy and staleness. Use during periodic library maintenance, after adding multiple new skills or rules, when a role's token budget is too high, or after retrospectives identify component issues.

Skill与智能体开发
★ 3
muratovv
muratovv/ai-hats

silent-fallback-gate

PreToolUse hook — refuses an Edit or Write that adds an inert broad except. Use when a Python edit was blocked for a silent fallback.

★ 3
muratovv
muratovv/ai-hats

retro-to-framework

Convert an observation about agent behavior — from a retrospective or from a single incident — into a framework-level change (hook, rule, skill, skill update). Use after a retrospective identifies problems that are not project-specific, after an incident where an agent misapplied a component it had read, when CLAUDE.md band-aids accumulate (more than 3 per-project rules that could be generic), or when the same problem recurs across multiple projects.

Skill与智能体开发
★ 3