Create-Architectural-Decision-Record
Create-Architectural-Decision-Record是一款data方向的AI技能，核心价值是Create an Architectural Decision Record (ADR) document for AI-optimized decision documentation，可用于解决开发者在data领域的实际问题，帮助用户提升效率、自动化重复任务或优化工作流。
Create an Architectural Decision Record (ADR) document for AI-optimized decision documentation.
mkdir -p ./skills/create-architectural-decision-record && curl -sfL https://raw.githubusercontent.com/github/awesome-copilot/main/skills/create-architectural-decision-record/SKILL.md -o ./skills/create-architectural-decision-record/SKILL.mdRun in terminal / PowerShell. Requires curl (Unix) or PowerShell 5+ (Windows).
Skill Content
# Create Architectural Decision Record
Create an ADR document for `${input:DecisionTitle}` using structured formatting optimized for AI consumption and human readability.
Inputs
- **Context**: `${input:Context}`
- **Decision**: `${input:Decision}`
- **Alternatives**: `${input:Alternatives}`
- **Stakeholders**: `${input:Stakeholders}`
Input Validation
If any of the required inputs are not provided or cannot be determined from the conversation history, ask the user to provide the missing information before proceeding with ADR generation.
Requirements
- Use precise, unambiguous language
- Follow standardized ADR format with front matter
- Include both positive and negative consequences
- Document alternatives with rejection rationale
- Structure for machine parsing and human reference
- Use coded bullet points (3-4 letter codes + 3-digit numbers) for multi-item sections
The ADR must be saved in the `/docs/adr/` directory using the naming convention: `adr-NNNN-[title-slug].md`, where NNNN is the next sequential 4-digit number (e.g., `adr-0001-database-selection.md`).
Required Documentation Structure
The documentation file must follow the template below, ensuring that all sections are filled out appropriately. The front matter for the markdown should be structured correctly as per the example following:
---
title: "ADR-NNNN: [Decision Title]"
status: "Proposed"
date: "YYYY-MM-DD"
authors: "[Stakeholder Names/Roles]"
tags: ["architecture", "decision"]
supersedes: ""
superseded_by: ""
---
# ADR-NNNN: [Decision Title]
## Status
**Proposed** | Accepted | Rejected | Superseded | Deprecated
## Context
[Problem statement, technical constraints, business requirements, and environmental factors requiring this decision.]
## Decision
[Chosen solution with clear rationale for selection.]
## Consequences
### Positive
- **POS-001**: [Beneficial outcomes and advantages]
- **POS-002**: [Performance, maintainability, scalability improvements]
- **POS-003**: [Alignment with architectural principles]
### Negative
- **NEG-001**: [Trade-offs, limitations, drawbacks]
- **NEG-002**: [Technical debt or complexity introduced]
- **NEG-003**: [Risks and future challenges]
## Alternatives Considered
### [Alternative 1 Name]
- **ALT-001**: **Description**: [Brief technical description]
- **ALT-002**: **Rejection Reason**: [Why this option was not selected]
### [Alternative 2 Name]
- **ALT-003**: **Description**: [Brief technical description]
- **ALT-004**: **Rejection Reason**: [Why this option was not selected]
## Implementation Notes
- **IMP-001**: [Key implementation considerations]
- **IMP-002**: [Migration or rollout strategy if applicable]
- **IMP-003**: [Monitoring and success criteria]
## References
- **REF-001**: [Related ADRs]
- **REF-002**: [External documentation]
- **REF-003**: [Standards or frameworks referenced]🎯 Best For
- Technical writers
- API documentation teams
- Claude users
- GitHub Copilot users
- Data professionals
💡 Use Cases
- Generating JSDoc/TSDoc comments
- Writing README files for new projects
- Data pipeline auditing
- Query optimization
📖 How to Use This Skill
- 1
Install the Skill
Copy the install command from the Terminal tab and run it. The SKILL.md file downloads to your local skills directory.
- 2
Load into Your AI Assistant
Open Claude or GitHub Copilot and reference the skill. Paste the SKILL.md content or use the system prompt tab.
- 3
Apply Create-Architectural-Decision-Record to Your Work
Provide context for your task — paste source material, describe your audience, or share existing work to guide the AI.
- 4
Review and Refine
Edit the AI output for accuracy, tone, and completeness. Add human insight where the AI lacks context.
❓ Frequently Asked Questions
Does it follow my documentation style?
Most documentation skills respect existing style. Provide a style guide or example in your prompt.
How do I install Create-Architectural-Decision-Record?
Copy the install command from the Terminal tab and run it. The skill downloads to ./skills/create-architectural-decision-record/SKILL.md, ready to use.
Can I customize this skill for my team?
Absolutely. Edit the SKILL.md file to add team-specific instructions, examples, or workflows.
⚠️ Common Mistakes to Avoid
Auto-generating without reviewing
AI documentation can contain inaccuracies. Always verify technical accuracy.
Ignoring data quality
AI analysis inherits all data quality issues — profile your data first.