d2da71e53a
- Reveal.js presentation on Skills and Subagents pattern - Nix flake with Caddy-based HTTP server and process-compose orchestration - ADRs documenting architectural decisions - Skills for AI implementation guidance - Full Scott Scoble author attribution in README
80 lines
2.8 KiB
Markdown
80 lines
2.8 KiB
Markdown
# Architecture Decision Records
|
||
|
||
This directory contains Architecture Decision Records (ADRs) for the "Beyond the Prompt" presentation project.
|
||
|
||
## Purpose: Human Documentation
|
||
|
||
**ADRs are for humans, not AI.** They explain WHY architectural decisions were made, document alternatives considered, and preserve historical context for team members.
|
||
|
||
**For AI implementation guidance**, see the `/skills` directory. Skills encode HOW to implement the decisions documented in ADRs.
|
||
|
||
## Index
|
||
|
||
1. [ADR 001: Presentation Technology Choice](./001-presentation-technology.md) → *Skill: `revealjs-presentation`*
|
||
- Decision to use Reveal.js for the presentation
|
||
- Rationale, alternatives, and implementation approach
|
||
|
||
2. [ADR 002: Nix Flake Architecture](./002-nix-flake-architecture.md) → *Skill: `nix-http-server`*
|
||
- Multi-platform flake design
|
||
- App structure and devShell configuration
|
||
- **Key constraint**: No Python dependencies
|
||
|
||
3. [ADR 003: Demo Implementation Strategy](./003-demo-implementation-strategy.md) → *Skill: `adr-documentation`*
|
||
- Conversation-as-demo approach
|
||
- Meta-awareness and documentation strategy
|
||
|
||
## ADR Format
|
||
|
||
Each ADR follows this structure:
|
||
- **Status**: Proposed, Accepted, Deprecated, Superseded
|
||
- **Context**: The problem or situation
|
||
- **Decision**: What was decided
|
||
- **Rationale**: Why this decision was made (including alternatives)
|
||
- **Consequences**: Positive, negative, and mitigations
|
||
|
||
## When to Write an ADR
|
||
|
||
Create an ADR when making architectural decisions that:
|
||
- Affect multiple parts of the system
|
||
- Have long-term implications
|
||
- Involve trade-offs between alternatives
|
||
- Need to be communicated to future contributors
|
||
|
||
**After writing an ADR**, consider creating a corresponding **Skill** if:
|
||
- The decision involves repetitive implementation patterns
|
||
- AI should automatically enforce the decision's constraints
|
||
- The pattern can be automated with templates/scripts
|
||
- You want perfect consistency in implementation
|
||
|
||
## The ADR + Skill Pattern
|
||
|
||
```
|
||
Make Decision
|
||
↓
|
||
┌────┴────┐
|
||
▼ ▼
|
||
ADR Skill
|
||
↓ ↓
|
||
WHY HOW
|
||
Human AI
|
||
```
|
||
|
||
**Example**: ADR 002 documents WHY we chose Caddy (no Python constraint). The `nix-http-server` skill enforces this by NEVER suggesting Python servers.
|
||
|
||
## Context Efficiency
|
||
|
||
**Old approach**: Load ADRs into AI context
|
||
- 3 ADRs × 1,500 tokens = 4,500 tokens before writing code
|
||
- Doesn't scale beyond ~10-20 ADRs
|
||
|
||
**New approach**: Use Skills for AI, ADRs for humans
|
||
- 3 skills × 100 tokens metadata = 300 tokens
|
||
- Scales to 100s of patterns
|
||
- ADRs remain available for human readers
|
||
|
||
## Updating ADRs
|
||
|
||
ADRs are immutable once accepted. To change a decision:
|
||
1. Create a new ADR that supersedes the old one
|
||
2. Update the old ADR's status to "Superseded by ADR XXX"
|
||
3. Update or create corresponding skill to reflect new implementation pattern
|