setup-adrs
Create the foundational Architecture Decision Record (ADR) sequence for a new project. Use after bootstrap-project, when establishing decision documentation, or when standardizing ADR practices.
jrjsmrtn · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add jrjsmrtn/project-orchestration-skills --skill setup-adrs技能说明
name: setup-adrs description: Create the foundational Architecture Decision Record (ADR) sequence for a new project. Use after bootstrap-project, when establishing decision documentation, or when standardizing ADR practices. metadata: author: "Georges Martin jrjsmrtn@gmail.com" version: "0.1.34" license: MIT
Foundation ADRs
Create the foundational Architecture Decision Record (ADR) sequence for a new project.
When to Use
- After running
bootstrap-projectskill - When establishing decision documentation for an existing project
- When standardizing ADR practices across projects
Required Inputs
- Project name and description (from CLAUDE.md or user)
- Project type: Development, Infrastructure, or Hybrid
- Technology stack decision and rationale
- Development practices to adopt (can use defaults)
- Operations requirements (critical for Infrastructure projects)
- Project-specific constraints or requirements
Foundational ADR Framework
Every project should have these foundational ADRs:
| ADR | Purpose | Scope | Critical For |
|---|---|---|---|
| ADR-0001 | HOW TO DECIDE | Decision methodology | All projects |
| ADR-0002 | HOW TO DEVELOP | Development practices | All projects |
| ADR-0003 | WHAT TECH | Technology stack | All projects |
| ADR-0004 | HOW TO OPERATE | Operations practices | Infrastructure, Hybrid (optional) |
Note: ADR-0004 is only needed for Infrastructure and Hybrid projects. Skip it for pure development projects (libraries, CLI tools, web apps without self-hosting concerns).
Audience Traceability
ADRs serve the Contribution audience category (maintainers, contributors, future architects). They provide the "understanding-oriented" content in Diátaxis terms, explaining why decisions were made.
If a SPARK Audience Registry exists for the project, tag ADRs with the registry's identifier for the Contribution audience:
---
audience: contribution # or the project's registry ID for maintainers/contributors
---
Pattern Reference: See AUDIENCE-DRIVEN ARTIFACTS
ADR Numbering Convention
Before creating ADRs, check for existing ones to prevent conflicts:
# Check highest ADR number
ls docs/adr/*.md 2>/dev/null | grep -E '[0-9]{4}-' | sort -V | tail -1
# If no ADRs exist, start with 0001
Filename: NNNN-title-with-hyphens.md (e.g., 0001-record-architecture-decisions.md)
Title: # N. Title using adr-tools format (e.g., # 1. Record Architecture Decisions). This format is required for Structurizr !adrs integration.
Workflow
ADR-0001: Record Architecture Decisions
Create docs/adr/0001-record-architecture-decisions.md:
# 1. Record Architecture Decisions
Date: [YYYY-MM-DD]
## Status
Accepted
## Context
[Project name] requires a systematic approach to documenting significant architectural and technical decisions. As the project evolves, we need to maintain a clear record of why decisions were made, what alternatives were considered, and what trade-offs were accepted.
This is especially important for AI-assisted development, where decisions made in one session need to be understood in future sessions.
## Decision
We will use Architecture Decision Records (ADRs) to document significant architectural decisions.
**ADR Location**: All ADRs stored in `docs/adr/` directory
**ADR Format**: Following the format established by Michael Nygard:
- **Title**: Short noun phrase (ADR-NNNN: Title)
- **Status**: Proposed, Accepted, Deprecated, Superseded
- **Context**: Forces at play, including technical, business, and social
- **Decision**: The response to these forces
- **Consequences**: Resulting context after applying the decision
**Numbering**: Sequential four-digit format (0001, 0002, ...) with no gaps
**What Warrants an ADR**:
- Technology stack choices
- Architectural patterns adopted
- Build/deployment approaches
- Integration decisions
- Security-related choices
- Decisions that would be costly to reverse
## Consequences
**Positive**:
- Clear record of why decisions were made
- Context preserved for future maintainers and AI assistants
- Reduced repeated discussions about settled decisions
- Audit trail for architectural evolution
**Negative**:
- Overhead of writing and maintaining ADRs
- Risk of ADRs becoming outdated if not maintained
## References
- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) - Michael Nygard
- [ADR GitHub Organization](https://adr.github.io/)
ADR-0002: Adopt Development Best Practices
Create docs/adr/0002-adopt-development-best-practices.md:
Scale the detail to the project. A small CLI tool needs ~100 lines; a multi-subsystem application may need 300-700 lines. Include only sections that apply.
# 2. Adopt Development Best Practices
Date: [YYYY-MM-DD]
## Status
Accepted
## Context
[Project name] is a [type] project using [technology stack]. We need consistent development practices that enable high-quality, maintainable code while supporting AI-assisted development workflows.
This project follows [AI-Assisted Project Orchestration patterns](https://github.com/jrjsmrtn/ai-assisted-project-orchestration).
## Decision
### 1. Testing Strategy
- **Framework**: [ecosystem-specific: ExUnit, pytest, cargo test, etc.]
- **Approach**: TDD — Red-Green-Refactor cycle
- **Coverage target**: >80% for core logic
- **Test organization**:
- `test/unit/` or `test/[app]/` — unit tests (fast, isolated)
- `test/integration/` — integration tests (slower, may require external services)
[For Elixir: add property-based testing with StreamData if applicable]
[For Elixir: add contract tests if defining behaviours]
### 2. BDD with Gherkin (user-facing projects)
[Include th
阅读完整来源 ↗