majiayu000/spellbook / skills/technical-spec
technical-spec
VerifiedTechnical specification and design document expert. Use when writing design docs, RFCs, ADRs, or evaluating technology choices. Covers C4 model, system design, and architecture documentation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.9 KB |
| reference/adr.md | markdown | 18.0 KB |
| reference/c4-model.md | markdown | 23.1 KB |
| reference/design-doc.md | markdown | 20.0 KB |
| reference/extended.md | markdown | 3.9 KB |
| reference/tech-selection.md | markdown | 16.4 KB |
| templates/adr-template.md | markdown | 5.2 KB |
| templates/design-doc-template.md | markdown | 11.7 KB |
templates/adr-template.md
View on GitHub# ADR-XXX: [Short Title of Decision]
## Status
Proposed | Accepted | Deprecated | Superseded
**Date**: YYYY-MM-DD
**Supersedes**: [ADR-YYY](./YYY-previous-decision.md) _(if applicable)_
**Superseded by**: [ADR-ZZZ](./ZZZ-new-decision.md) _(if applicable)_
---
## Context
[Describe the context and background of the decision. What problem are we trying to solve? What constraints do we have?]
**Problem Statement**:
[1-2 paragraphs describing the problem]
**Requirements**:
- [Requirement 1]
- [Requirement 2]
- [Requirement 3]
**Constraints**:
- [Constraint 1: e.g., budget, timeline, team skills]
- [Constraint 2]
- [Constraint 3]
**Current Situation** _(if applicable)_:
[Describe what exists today and why it's insufficient]
---
## Considered Options
### Option 1: [Name]
**Description**:
[How this option works]
**Pros**:
- ✅ [Advantage 1]
- ✅ [Advantage 2]
- ✅ [Advantage 3]
**Cons**:
- ❌ [Disadvantage 1]
- ❌ [Disadvantage 2]
- ❌ [Disadvantage 3]
**Cost/Effort**:
[Time, money, or complexity estimate]
---
### Option 2: [Name]
**Description**:
[How this option works]
**Pros**:
- ✅ [Advantage 1]
- ✅ [Advantage 2]
- ✅ [Advantage 3]
**Cons**:
- ❌ [Disadvantage 1]
- ❌ [Disadvantage 2]
- ❌ [Disadvantage 3]
**Cost/Effort**:
[Time, money, or complexity estimate]
---
### Option 3: [Name]
[Repeat for additional options]
---
## Decision
We will use **[Chosen Option]**.
### Rationale
[Explain why this option was selected over the alternatives. Reference specific requirements or constraints.]
**Key factors in the decision**:
1. [Factor 1: e.g., "Meets performance requirements while staying within budget"]
2. [Factor 2: e.g., "Team already has expertise in this technology"]
3. [Factor 3: e.g., "Lowest long-term maintenance burden"]
**Trade-offs accepted**:
- [Trade-off 1: What we're giving up for this choice]
- [Trade-off 2]
---
## Consequences
### Positive Consequences
- ✅ [Benefit 1]
- ✅ [Benefit 2]
- ✅ [Benefit 3]
### Negative Consequences
- ❌ [Drawback 1]
- ❌ [Drawback 2]
- ❌ [Drawback 3]
### Mitigations
[How we'll address the negative consequences]
| Negative Consequence | Mitigation Strategy |
|---------------------|---------------------|
| [Drawback 1] | [How we'll mitigate] |
| [Drawback 2] | [How we'll mitigate] |
### Neutral Consequences
- [Consequence that's neither good nor bad]
- [Another neutral impact]
---
## Implementation Notes
[Optional: Any important details about implementing this decision]
**Key actions**:
- [ ] [Action item 1]
- [ ] [Action item 2]
- [ ] [Action item 3]
**Timeline**:
- [Milestone 1]: [Date]
- [Milestone 2]: [Date]
**Dependencies**:
- [Dependency 1]
- [Dependency 2]
---
## Related ADRs
- [ADR-YYY: Related Decision 1](./YYY-related-decision.md)
- [ADR-ZZZ: Related Decision 2](./ZZZ-another-decision.md)
---
## References
- [External article or documentation](https://example.com)
- [Internal design doc](../design/design-doc.md)
- [Vendor comparison](https://example.com/comparison)
---
## Review & Approval
**Reviewers**:
- @tech-lead: Approved | Rejected | Comments
- @team-member-1: Approved | Rejected | Comments
- @security-team: Approved | Rejected | Comments
**Discussion**: [Link to discussion thread, if applicable]
**Approval Date**: YYYY-MM-DD
---
## Revisions
| Date | Author | Change |
|------|--------|--------|
| YYYY-MM-DD | @author | Initial draft |
| YYYY-MM-DD | @author | Updated based on feedback |
| YYYY-MM-DD | @author | Accepted |
---
## Alternative Templates
### Y-Statement Format (Compact)
Use this simplified format for straightforward decisions:
```markdown
# ADR-XXX: [Title]
## Status
Accepted
## Decision Statement
In the context of [use case/user story],
facing [concern],
we decided for [option]
to achieve [quality],
accepting [downside].
## Consequences
**Benefits**:
- [Benefit 1]
- [Benefit 2]
**Risks**:
- [Risk 1]
- [Risk 2]
**Mitigations**:
- [How we mitigate risks]
```
---
### Michael Nygard Format (Original)
Use this format for complex architectural decisions:
```markdown
# ADR-XXX: [Title]
## Status
Accepted
## Context
[Describe the forces at play: technical, political, social, project-local.
These forces are probably in tension and should be called out as such.
Leave no stone unturned: look at both sides of every trade-off.]
## Decision
[Describe the response to the forces. State the decision in full sentences,
with active voice: "We will ..."]
## Consequences
[Describe the resulting context after applying the decision. All consequences
should be listed, not just the "positive" ones. A decision may have positive,
negative, and neutral consequences.]
```
---
## Tips for Writing Good ADRs
1. **Keep it short** — 1-2 pages maximum
2. **Focus on the decision** — Not implementation details
3. **Show your work** — Include alternatives considered
4. **Be specific** — Avoid vague language
5. **Make it searchable** — Use clear titles and keywords
6. **Immutable after acceptance** — Change status, don't edit content
7. **Link to related docs** — Design docs, other ADRs
8. **Include dates** — When decided, when superseded
9. **Get peer review** — Multiple perspectives improve decisions
10. **Update status** — Keep status current (Proposed → Accepted → Superseded)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |