菜单
Guide for writing Architecture Decision Records (ADR). Use when documenting architectural decisions, recording technology choices, or creating technical decision logs. This skill defines the ADR structure, format, and best practices.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | adr-skill |
| description | Guide for writing Architecture Decision Records (ADR). Use when documenting architectural decisions, recording technology choices, or creating technical decision logs. This skill defines the ADR structure, format, and best practices. |
ADR is a short text file that documents crucial architectural decisions in software projects.
| Purpose | Description |
|---|---|
| Knowledge Preservation | Record "why" specific technical selections were made |
| Onboarding | New members quickly grasp project's technical history |
| Avoiding Repetition | Prevent revisiting settled discussions |
| Accountability | Transparent records of who decided what and when |
ADRs solve "architecture amnesia" by preventing loss of institutional knowledge.
docs/adr/
├── ADR-001-database-selection.md
├── ADR-002-authentication-method.md
├── ADR-003-api-versioning-strategy.md
└── ...
Naming Convention: ADR-{NUMBER}-{kebab-case-title}.md
# ADR-{NUMBER}: {Title}
## Status
{Proposed | Accepted | Deprecated | Superseded by ADR-XXX}
## Date
{YYYY-MM-DD}
## Context
{Background information and constraints driving the decision.
What is the issue that we're seeing that is motivating this decision?}
## Decision
{The chosen approach, clearly stated.
What is the change that we're proposing and/or doing?}
## Rationale
{Explanation of why this option was selected.
Why did we choose this over other alternatives?}
## Alternatives Considered
### {Alternative 1}
- Pros: ...
- Cons: ...
- Why rejected: ...
### {Alternative 2}
- Pros: ...
- Cons: ...
- Why rejected: ...
## Consequences
{System impacts and implementation implications.
What becomes easier or more difficult because of this change?}
### Positive
- ...
### Negative
- ...
### Risks
- ...
# ADR-001: Use PostgreSQL for Primary Database
## Status
Accepted
## Date
2024-03-15
## Context
We need to select a primary database for our new microservice.
The service requires ACID compliance, complex queries with joins,
and needs to handle approximately 10,000 transactions per second.
## Decision
We will use PostgreSQL as our primary database.
## Rationale
PostgreSQL provides robust ACID compliance, excellent performance
for complex queries, and has strong community support. Our team
has existing expertise with PostgreSQL.
## Alternatives Considered
### MySQL
- Pros: Widely adopted, good performance
- Cons: Less robust for complex queries
- Why rejected: PostgreSQL's advanced features better fit our needs
### MongoDB
- Pros: Flexible schema, horizontal scaling
- Cons: No ACID for multi-document transactions (at decision time)
- Why rejected: ACID compliance is a hard requirement
## Consequences
### Positive
- Strong data integrity guarantees
- Rich query capabilities
- Familiar technology for the team
### Negative
- Vertical scaling limitations
- Requires careful schema design upfront
### Risks
- May need sharding strategy for future growth
Proposed → Accepted → [Deprecated | Superseded by ADR-XXX]
| Status | Description |
|---|---|
| Proposed | Under discussion, not yet finalized |
| Accepted | Decision made and in effect |
| Deprecated | No longer relevant or applicable |
| Superseded | Replaced by a newer ADR |
Write an ADR when:
Guide for creating and managing configuration classes in this project. Use when creating new config classes, loading configuration from environment variables, implementing domain-specific configs (Redis, OpenAI, S3, etc.), integrating with FastAPI or LangGraph, or working with sensitive field masking. This skill defines the two-type config system: Settings (SettingsBase) for app-level config and ConfigBase (BaseModel) for domain configs.
Guide for Kubernetes deployments with Helm charts. Use when working with Helm charts, managing secrets across environments (dev, beta, prod), creating SealedSecrets, or configuring environment-specific values. This skill defines the secret management workflow using Bitnami SealedSecrets.
Guide for writing task plans and implementation plans. Use when starting a new task, creating a plan file, or updating plan progress.
Guide for managing pyproject.toml files in this uv workspace monorepo. Use when adding dependencies, creating new workspace members, or modifying build configuration.
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
Guide for writing and organizing tests in this project. Use when creating new tests, choosing test patterns, writing fixtures, or structuring test directories.