beyond-the-prompt/docs/adr/003-demo-implementation-strategy.md

ADR 003: Demo Implementation Strategy

Status

Accepted

Context

The presentation "Beyond the Prompt: Lessons from Building with Claude Code" needs to demonstrate:

• How to use ADRs to guide AI-assisted development
• Effective prompt engineering and task decomposition
• Iterative refinement with architectural constraints
• Real-world workflow patterns with Claude Code

The demo must be:

• Authentic and realistic
• Reproducible for attendees
• Illustrative of actual development patterns
• Version-controlled and sharable

Decision

The demo IS the development conversation itself - specifically, the conversation that builds this presentation system using ADRs to guide Claude Code.

The demo consists of:

1. The ADRs that define the architecture (stored in docs/adr/)
2. The conversation transcript showing iterative development
3. The resulting implementation (flake, presentation, etc.)

Rationale

Why Conversation-as-Demo

Authenticity: Shows real Claude Code usage, not simulation

• Actual tool interactions
• Real decision-making process
• Genuine iterative refinement
• True constraint handling

Educational Value: Demonstrates the meta-pattern

• ADRs provide clear boundaries and context
• Constraints drive better design (e.g., "no Python", "use nixpkgs")
• Iterative improvement based on feedback
• Architecture emerges from conversation

Reproducibility: Attendees can recreate the pattern

• ADRs are templates for their own projects
• Conversation style is learnable
• Git history shows evolution
• Implementation validates the approach

Alternative Approaches Considered

1. Scripted Demo with Simulated Output

• Pros: Predictable, rehearsable, no live risk
• Cons: Inauthentic, doesn't show real tool, feels staged
• Verdict: Misses the point of "beyond the prompt"

2. Live Coding Session

• Pros: Shows real tool, spontaneous
• Cons: Unpredictable, time pressure, can't capture nuance
• Verdict: Too risky for complex architecture decisions

3. Pre-recorded Video

• Pros: Perfect execution, editing possible
• Cons: Not interactive, can't adapt to audience questions
• Verdict: Loses conversational flow and learning opportunities

Implementation Details

Demo Artifacts

1. Architecture Decision Records (docs/adr/)

• 001-presentation-technology.md - Reveal.js choice
• 002-nix-flake-architecture.md - process-compose + Caddy
• 003-demo-implementation-strategy.md - This document (meta!)
• README.md - ADR index and usage guide

2. Conversation Transcript (docs/demo/) Store the actual Claude Code conversation showing:

• Initial requirements gathering
• ADR creation and refinement
• Constraint application ("no Python")
• Architecture evolution (simple → process-compose)
• Decision rationale and tradeoffs

3. Implementation Artifacts

• flake.nix - The actual working implementation
• presentation/ - Reveal.js presentation
• Git commits showing progression

Demo Execution Flow

Stage 1: Setup (2 minutes)

• Show empty repo with just README
• Explain the goal: build a presentation system
• Introduce ADRs as the guiding pattern

Stage 2: ADR Creation (3 minutes)

• Walk through creating ADR 001 (presentation tech)
• Show how it evaluates alternatives
• Demonstrate decision rationale

Stage 3: Constraint Refinement (3 minutes)

• Show conversation applying constraints
• Example: "No Python" → rearchitecture to Caddy
• Demonstrate ADR updates reflecting new decisions

Stage 4: Implementation Validation (2 minutes)

• Run nix run .#present to prove it works
• Show generated configs (Caddyfile, process-compose.yaml)
• Demonstrate configuration-as-code

Stage 5: Meta-Reflection (2 minutes)

• Highlight the pattern: ADRs → Conversation → Implementation
• Show how this approach is reusable
• Provide takeaways for attendees

Presentation Integration

Embed demo artifacts in the presentation:

# Slide: "The Power of ADRs"
- Show ADR 001 side-by-side with implementation
- Highlight how decisions map to code

# Slide: "Iterative Refinement"
- Show conversation excerpt about Python → Caddy
- Display the updated ADR section
- Show the resulting Nix code

# Slide: "Meta Demo"
- Reveal that THIS presentation was built this way
- Show the actual conversation
- Provide GitHub link for full exploration

Nix Integration

The demo app serves the conversation transcript:

demo = {
  type = "app";
  program = "${pkgs.writeScript "demo" ''
    #!/usr/bin/env bash

    # Generate demo config for process-compose
    config="${pkgs.writeText "demo-compose.yaml" (builtins.toJSON {
      processes = {
        conversation-viewer = {
          command = "${pkgs.caddy}/bin/caddy file-server --root ${self}/docs/demo --listen :8001";
        };
        presentation = {
          command = "${pkgs.caddy}/bin/caddy file-server --root ${self}/presentation --listen :8000";
        };
      };
    })}"

    exec ${pkgs.process-compose}/bin/process-compose up -f "$config"
  ''}";
};

This runs:

• Presentation on :8000
• Conversation transcript viewer on :8001

Technical Considerations

Conversation Capture

• Export Claude Code conversation to markdown
• Format with syntax highlighting
• Preserve timestamps and flow
• Annotate with insights

Presentation Structure

presentation/
├── index.html              # Main reveal.js presentation
├── slides/
│   ├── 01-introduction.md
│   ├── 02-the-adr-pattern.md
│   ├── 03-demo-reveal.md   # The meta moment
│   └── 04-takeaways.md
└── assets/
    ├── conversation.md     # Embedded transcript excerpts
    ├── adr-examples/       # ADR screenshots
    └── implementation/     # Code snippets

Git History as Artifact

Commit strategy:

feat: initial ADRs for presentation architecture
feat: update ADR 002 with process-compose approach
feat: rewrite ADR 003 as conversation-based demo
feat: implement flake based on ADR decisions
docs: add conversation transcript to demo/

Git history itself becomes part of the demo narrative.

Consequences

Positive

• Authentic: Real Claude Code usage, not simulation
• Educational: Shows thinking process, not just results
• Reusable: Pattern applicable to any project
• Transparent: All decisions documented and traceable
• Self-documenting: The demo explains itself
• Meta-awareness: Presentation about AI development, built with AI

Negative

• Complexity: More sophisticated than simple script
• Preparation: Requires curating conversation for clarity
• Length: Full conversation may be too detailed for presentation
• Assumption: Assumes audience familiarity with ADRs

Mitigation

• Curate conversation to key decision points
• Provide full transcript as supplementary material
• Include ADR primer in presentation intro
• Offer simplified "getting started" guide for newcomers

Future Enhancements

• Interactive conversation explorer (search, filter by topic)
• Side-by-side view: ADR ↔ Conversation ↔ Implementation
• Jupyter notebook walking through the process step-by-step
• Template repository: "instant ADR-driven development"
• Video walkthrough with narration over the conversation
• Browser extension to capture Claude Code conversations automatically

Key Insight

This ADR is itself part of the demo - it documents the decision to use the conversation as the demo, demonstrating the recursive, self-referential nature of effective AI-assisted development.

The presentation is its own case study.