From 39644978ca77922468e25b39bca8af6b1835ea3c Mon Sep 17 00:00:00 2001 From: Jeremy Eder Date: Mon, 5 Jan 2026 02:49:37 -0500 Subject: [PATCH 1/2] docs: scaffold GitHub Pages with MkDocs and documentation structure Add MkDocs configuration with Material theme and Mermaid support. Add GitHub Actions workflow for deploying to GitHub Pages. Scaffold documentation structure with exec summaries and section outlines for patterns, getting started guides, and resources. --- .github/workflows/deploy-docs.yml | 55 ++++++++ .markdownlint.json | 1 + docs/getting-started/first-cba.md | 78 ++++++++++ docs/getting-started/installation.md | 54 +++++++ docs/index.md | 188 +++++++++++++++++++++++++ docs/patterns/codebase-agent.md | 76 ++++++++++ docs/patterns/dependabot-auto-merge.md | 57 ++++++++ docs/patterns/index.md | 84 +++++++++++ docs/patterns/issue-to-pr.md | 74 ++++++++++ docs/patterns/layered-architecture.md | 69 +++++++++ docs/patterns/pr-auto-review.md | 56 ++++++++ docs/patterns/security-patterns.md | 59 ++++++++ docs/patterns/stale-issues.md | 65 +++++++++ docs/patterns/testing-patterns.md | 59 ++++++++ docs/resources/coloring-book.md | 67 +++++++++ docs/resources/demo-app.md | 51 +++++++ docs/resources/presentation.md | 47 +++++++ mkdocs.yml | 105 ++++++++++++++ 18 files changed, 1245 insertions(+) create mode 100644 .github/workflows/deploy-docs.yml create mode 100644 docs/getting-started/first-cba.md create mode 100644 docs/getting-started/installation.md create mode 100644 docs/index.md create mode 100644 docs/patterns/codebase-agent.md create mode 100644 docs/patterns/dependabot-auto-merge.md create mode 100644 docs/patterns/index.md create mode 100644 docs/patterns/issue-to-pr.md create mode 100644 docs/patterns/layered-architecture.md create mode 100644 docs/patterns/pr-auto-review.md create mode 100644 docs/patterns/security-patterns.md create mode 100644 docs/patterns/stale-issues.md create mode 100644 docs/patterns/testing-patterns.md create mode 100644 docs/resources/coloring-book.md create mode 100644 docs/resources/demo-app.md create mode 100644 docs/resources/presentation.md create mode 100644 mkdocs.yml diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000..3af7708 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,55 @@ +name: Deploy Documentation + +on: + push: + branches: [main] + paths: + - "docs/**" + - "mkdocs.yml" + - ".github/workflows/deploy-docs.yml" + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + + - name: Install dependencies + run: | + pip install mkdocs-material mkdocs-mermaid2-plugin + + - name: Build documentation + run: mkdocs build --strict + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: site + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.markdownlint.json b/.markdownlint.json index a64c768..25ba725 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -3,5 +3,6 @@ "MD013": false, "MD033": false, "MD041": false, + "MD046": false, "MD051": false } diff --git a/docs/getting-started/first-cba.md b/docs/getting-started/first-cba.md new file mode 100644 index 0000000..4b69c8a --- /dev/null +++ b/docs/getting-started/first-cba.md @@ -0,0 +1,78 @@ +# Your First Codebase Agent + +**Create a CBA in 30 minutes.** + +--- + +## Overview + +!!! note "Section Summary" + What you'll build: a `.claude/` directory with agent definition and context files customized for your project. By the end, AI will know your coding conventions. + +--- + +## Step 1: Copy the Template + +!!! note "Section Summary" + Copy `.claude/` from reference repo to your project. Directory structure explanation. What each file does. + +--- + +## Step 2: Customize the Agent Definition + +!!! note "Section Summary" + Edit `.claude/agents/codebase-agent.md`. Key sections to customize: capability boundaries (what can the agent do autonomously?), quality gates (your linting/testing commands), safety guardrails (when to stop and ask). + +--- + +## Step 3: Create Context Files + +### Architecture Context + +!!! note "Section Summary" + `.claude/context/architecture.md` - describe your layers, component responsibilities, data flow. Template provided. Examples for common stacks (FastAPI, Express, Django). + +### Security Context + +!!! note "Section Summary" + `.claude/context/security-standards.md` - your validation rules, sanitization patterns, secrets management approach. What to validate, what to trust. + +### Testing Context + +!!! note "Section Summary" + `.claude/context/testing-patterns.md` - your test pyramid, where tests live, mocking conventions, coverage targets. + +--- + +## Step 4: Test Your CBA + +!!! note "Section Summary" + Interactive session: ask AI to perform a task in your codebase. Verify it follows conventions. Iterate on context files based on what it gets wrong. + +--- + +## Step 5: Share with Your Team + +!!! note "Section Summary" + Commit `.claude/` to your repo. Team onboarding: everyone gets the same AI behavior. Updating context files: when and how. + +--- + +## Memory System Deep Dive + +!!! note "Section Summary" + How modular context works. Loading context on-demand. Token efficiency. When to split vs combine context files. + +--- + +## Troubleshooting + +!!! note "Section Summary" + Common issues: AI ignores context (file not loaded), AI makes up conventions (context too vague), AI over-engineers (context too broad). Solutions for each. + +--- + +## Next Steps + +- [Patterns Index](../patterns/index.md) - Explore all available patterns +- [Self-Review Reflection](../patterns/self-review-reflection.md) - Add quality gates to your CBA diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 0000000..f66902e --- /dev/null +++ b/docs/getting-started/installation.md @@ -0,0 +1,54 @@ +# Installation + +**Set up tooling for AI-assisted development.** + +--- + +## Prerequisites + +!!! note "Section Summary" + This section covers required and recommended tooling: Python 3.11+, uv package manager, Claude CLI or API access, markdownlint, and Mermaid CLI. Includes verification commands for each tool. + +--- + +## Quick Install + +!!! note "Section Summary" + One-liner install scripts for macOS/Linux. Clone reference repo, install dependencies with uv, verify setup with validation scripts. + +--- + +## Tool-by-Tool Setup + +### Python Environment + +!!! note "Section Summary" + Virtual environment setup with uv. Why uv over pip (speed, reliability). Verification steps. + +### Claude CLI / API + +!!! note "Section Summary" + Claude Code installation and authentication. API key management. Verification that Claude can access your codebase. + +### Linting Tools + +!!! note "Section Summary" + markdownlint-cli installation. Black, isort, ruff for Python. Configuration files included in reference repo. + +### Mermaid Validation + +!!! note "Section Summary" + @mermaid-js/mermaid-cli installation. Why Mermaid validation matters for documentation CI. + +--- + +## Verification + +!!! note "Section Summary" + Run all validation scripts to confirm installation. Expected output for each. Troubleshooting common issues. + +--- + +## Next Steps + +- [Your First CBA](first-cba.md) - Create your first Codebase Agent diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..74e933c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,188 @@ +# Ambient Code Reference + +**AI-assisted development patterns for engineering teams.** + +--- + +## Executive Summary + +This repository provides battle-tested patterns for adopting AI-assisted development at scale. It answers the question every principal engineer faces: *"How do we use AI coding assistants without creating chaos?"* + +**Key Value Propositions:** + +1. **Consistency** - Every AI interaction follows the same process +2. **Safety** - Human review gates prevent runaway automation +3. **Productivity** - 10x speedup for routine tasks +4. **Transferability** - Patterns work across tools and languages + +**Approach:** Standalone patterns. Adopt what you need, skip what you don't. No prescribed sequence. + +--- + +## What's Inside + +### Patterns (9 Total) + +| Pattern | Category | Effort | Impact | +|---------|----------|--------|--------| +| [Codebase Agent (CBA)](#cba) | Agent Behavior | Medium | High | +| [Memory System](#memory) | Agent Behavior | Low | Medium | +| [Self-Review Reflection](#self-review) | Agent Behavior | Low | High | +| [Issue-to-PR Automation](#issue-to-pr) | GHA Automation | High | Very High | +| [PR Auto-Review](#pr-review) | GHA Automation | Medium | High | +| [Dependabot Auto-Merge](#dependabot) | GHA Automation | Low | Medium | +| [Stale Issue Management](#stale) | GHA Automation | Low | Medium | +| [Layered Architecture](#architecture) | Foundation | Low | Medium | +| [Security Patterns](#security) | Foundation | Low | Medium | + +### Quick Start Paths + +=== "I want consistent AI assistance" + + Start with [Codebase Agent](patterns/codebase-agent.md) - one file that defines how AI works in your codebase. + +=== "AI keeps forgetting my conventions" + + Start with [Memory System](getting-started/first-cba.md#memory-system) - modular context files that persist across sessions. + +=== "Routine fixes take too long" + + Start with [Issue-to-PR Automation](patterns/issue-to-pr.md) - convert well-defined issues to PRs automatically. + +=== "I want to see it working first" + + Check out the [demo-fastapi](https://github.com/jeremyeder/demo-fastapi) repository for a working example. + +--- + +## Documentation Structure + +### Getting Started + +| Section | Purpose | Time | +|---------|---------|------| +| [Quickstart](quickstart.md) | 5-minute introduction to AI-assisted development | 5 min | +| [Installation](getting-started/installation.md) | Set up tooling and dependencies | 15 min | +| [Your First CBA](getting-started/first-cba.md) | Create your first Codebase Agent | 30 min | + +**What you'll learn:** How to copy the `.claude/` directory to your project and customize it for your tech stack. + +--- + +### Patterns + +#### Agent Behavior Patterns + +How AI agents behave during development. + +| Pattern | What It Does | Section Summary | +|---------|--------------|-----------------| +| [Codebase Agent](patterns/codebase-agent.md) | Defines AI behavior, capabilities, and guardrails | Agent definition structure, autonomy levels, workflow examples, capability boundaries | +| [Self-Review Reflection](patterns/self-review-reflection.md) | Agent reviews own work before presenting | Reflection loop, checklist criteria, implementation prompts, anti-patterns | +| [Autonomous Quality](patterns/autonomous-quality-enforcement.md) | Validates code quality before delivery | Lint loops, test verification, error budgets | +| [Multi-Agent Review](patterns/multi-agent-code-review.md) | Multiple specialized agents review in parallel | Agent roles, consensus mechanisms, conflict resolution | + +#### GHA Automation Patterns + +Proactive CI/CD workflows. + +| Pattern | Trigger | Section Summary | +|---------|---------|-----------------| +| [Issue-to-PR](patterns/issue-to-pr.md) | `issues.opened` | Requirements analysis, draft PR creation, risk categories, safety gates | +| [PR Auto-Review](patterns/pr-auto-review.md) | `pull_request` | AI review format, severity levels, when to block vs comment | +| [Dependabot Auto-Merge](patterns/dependabot-auto-merge.md) | `pull_request` | Patch vs minor/major, CI requirements, safety conditions | +| [Stale Issues](patterns/stale-issues.md) | `schedule` | Inactivity thresholds, warning periods, exempt labels | + +#### Foundation Patterns + +Enabling patterns that make AI more effective. + +| Pattern | Purpose | Section Summary | +|---------|---------|-----------------| +| [Layered Architecture](patterns/layered-architecture.md) | Code structure AI can reason about | Four layers, dependency rules, component responsibilities | +| [Security Patterns](patterns/security-patterns.md) | Practical protection without over-engineering | Boundary validation, sanitization, secrets management | +| [Testing Patterns](patterns/testing-patterns.md) | Test pyramid approach | Unit/integration/E2E, coverage targets, AI test generation | + +--- + +### Reference + +| Section | Purpose | Contents | +|---------|---------|----------| +| [Architecture](architecture.md) | Deep dive into architecture patterns | Data flow diagrams, layer boundaries, extension points | +| [API Patterns](api-reference.md) | API design for AI-assisted development | Request/response patterns, error handling, OpenAPI | +| [ADR Template](adr/template.md) | Decision record scaffolding | YYYYMMDD-title.md format, context/decision/consequences | + +--- + +### Tutorial + +| Section | Purpose | Time | +|---------|---------|------| +| [Full Tutorial](tutorial.md) | Step-by-step implementation guide | 2-4 hours | + +**What you'll build:** A complete AI-assisted development setup from scratch, including CBA, memory system, and GHA automations. + +--- + +### Resources + +| Resource | Format | Purpose | +|----------|--------|---------| +| [Coloring Book](resources/coloring-book.md) | PDF/Interactive | Visual guide to concepts (follow-on to SRE Coloring Book) | +| [Presentation](resources/presentation.md) | Markdown | NotebookLM podcast generation, 9 features explained | +| [Demo Application](resources/demo-app.md) | GitHub Repo | Working FastAPI example | + +--- + +## Navigation Guide + +```mermaid +flowchart TD + A[Start Here] --> B{What do you need?} + B -->|Understand the concepts| C[Quickstart] + B -->|See it working| D[Demo App] + B -->|Implement patterns| E[Tutorial] + B -->|Reference specific pattern| F[Patterns Index] + + C --> G[Your First CBA] + D --> G + E --> G + F --> H[Choose Pattern] + + G --> I[Production Setup] + H --> I +``` + +--- + +## Design Principles + +1. **Standalone patterns** - No dependencies between patterns. Adopt one without adopting others. +2. **Copy-paste ready** - All configurations are complete and ready to customize. +3. **Human-in-the-loop** - AI assists, humans decide. Safety gates everywhere. +4. **Vendor-agnostic** - Patterns work with any AI tool or none at all. +5. **Minimal ceremony** - Start small, add complexity only when needed. + +--- + +## Who This Is For + +| Role | Benefit | +|------|---------| +| **Principal Engineers** | Evaluate AI adoption strategy with battle-tested patterns | +| **Team Leads** | Implement consistent AI workflows across your team | +| **Senior Developers** | Get productivity gains without sacrificing quality | +| **Junior Developers** | Get senior-level AI assistance with guardrails | + +--- + +## Quick Links + +- **GitHub Repository**: [jeremyeder/reference](https://github.com/jeremyeder/reference) +- **Demo Application**: [jeremyeder/demo-fastapi](https://github.com/jeremyeder/demo-fastapi) +- **Original SRE Coloring Book**: [red.ht/sre-coloring-book](https://red.ht/sre-coloring-book) + +--- + +*"Stable, Secure, Performant, and Boring" - the goal is to make AI assistance invisible through excellence.* diff --git a/docs/patterns/codebase-agent.md b/docs/patterns/codebase-agent.md new file mode 100644 index 0000000..681c6b1 --- /dev/null +++ b/docs/patterns/codebase-agent.md @@ -0,0 +1,76 @@ +# Codebase Agent (CBA) + +**Single source of truth for AI behavior in your codebase.** + +--- + +## Overview + +!!! note "Section Summary" + What a CBA is: a markdown file that defines how AI works in your project. Problem it solves: inconsistent AI behavior across developers. Key benefit: every AI interaction follows the same process. + +--- + +## Quick Start + +!!! note "Section Summary" + Copy-paste the CBA definition from `.claude/agents/codebase-agent.md`. Minimal customization: your linting commands, your test commands. Done in 15 minutes. + +--- + +## Agent Definition Structure + +### Capability Boundaries + +!!! note "Section Summary" + What the agent can do autonomously vs what requires human approval. Examples: formatting changes (auto), architecture changes (human approval). How to define your own boundaries. + +### Workflow Definitions + +!!! note "Section Summary" + Step-by-step processes for common tasks: issue-to-PR, code review, refactoring. Template workflows provided. How to customize for your process. + +### Quality Gates + +!!! note "Section Summary" + Linting, testing, and review requirements. Which tools to run, in what order. What constitutes a passing gate. Error handling. + +### Safety Guardrails + +!!! note "Section Summary" + When to stop and ask for human input. Risk categories: low/medium/high. Examples of each. How to configure alert thresholds. + +--- + +## Autonomy Levels + +!!! note "Section Summary" + Level 1 (Conservative): PR creation only, wait for human approval. Level 2 (Moderate): Auto-merge for low-risk changes. Level 3 (Aggressive): Auto-deploy after tests pass. How to graduate between levels. + +--- + +## Memory System Integration + +!!! note "Section Summary" + How CBA uses context files from `.claude/context/`. Loading context on-demand. When to reference which context file. + +--- + +## Real-World Examples + +!!! note "Section Summary" + CBA configurations for different stacks: Python/FastAPI, TypeScript/Express, Go. What's different, what's the same. + +--- + +## Troubleshooting + +!!! note "Section Summary" + Common issues: agent ignores boundaries, agent is too conservative, agent makes up conventions. Solutions for each. + +--- + +## Related Patterns + +- [Self-Review Reflection](self-review-reflection.md) - Add quality gates to CBA output +- [Memory System](../getting-started/first-cba.md#memory-system) - Persistent context across sessions diff --git a/docs/patterns/dependabot-auto-merge.md b/docs/patterns/dependabot-auto-merge.md new file mode 100644 index 0000000..d9c8345 --- /dev/null +++ b/docs/patterns/dependabot-auto-merge.md @@ -0,0 +1,57 @@ +# Dependabot Auto-Merge + +**Automatically merge low-risk dependency updates.** + +--- + +## Overview + +!!! note "Section Summary" + When Dependabot creates a PR for a patch version update, auto-merge after CI passes. Keep dependencies current without manual effort. Minor/major updates still require human review. + +--- + +## Quick Start + +!!! note "Section Summary" + Copy the workflow YAML. No additional secrets needed. Enable Dependabot in your repo. Watch patch updates auto-merge. + +--- + +## How It Works + +```mermaid +flowchart TD + A[Dependabot PR] --> B{Patch Version?} + B -->|No| C[Require Human Review] + B -->|Yes| D{CI Passes?} + D -->|No| C + D -->|Yes| E[Auto-Merge] +``` + +--- + +## Safety Conditions + +!!! note "Section Summary" + Only auto-merge when ALL conditions met: author is dependabot[bot], update is patch version, all CI checks pass, no merge conflicts. Why each condition matters. + +--- + +## Workflow YAML + +!!! note "Section Summary" + Complete workflow file. Dependabot metadata action. Conditional auto-merge. Squash and delete branch. + +--- + +## Customization + +!!! note "Section Summary" + Auto-merge minor versions too. Exclude specific packages. Custom merge strategy. Notifications. + +--- + +## Related Patterns + +- [Stale Issue Management](stale-issues.md) - Another proactive cleanup pattern diff --git a/docs/patterns/index.md b/docs/patterns/index.md new file mode 100644 index 0000000..53b6ec8 --- /dev/null +++ b/docs/patterns/index.md @@ -0,0 +1,84 @@ +# Patterns Index + +**All AI-assisted development patterns in one place.** + +--- + +## Overview + +!!! note "Section Summary" + Patterns are organized into three categories: Agent Behavior (how AI works), GHA Automation (proactive CI/CD), and Foundation (enabling patterns). Each pattern is standalone - adopt what you need. + +--- + +## Agent Behavior Patterns + +How AI agents behave during development. + +| Pattern | Effort | Impact | Description | +|---------|--------|--------|-------------| +| [Codebase Agent](codebase-agent.md) | Medium | High | Single source of truth for AI behavior | +| [Self-Review Reflection](self-review-reflection.md) | Low | High | Agent reviews own work before presenting | +| [Autonomous Quality Enforcement](autonomous-quality-enforcement.md) | Medium | High | Validate code before delivery | +| [Multi-Agent Code Review](multi-agent-code-review.md) | High | Very High | Parallel specialized reviews | + +--- + +## GHA Automation Patterns + +Proactive CI/CD workflows that reduce toil. + +| Pattern | Trigger | Effort | Impact | +|---------|---------|--------|--------| +| [Issue-to-PR](issue-to-pr.md) | `issues.opened` | High | Very High | +| [PR Auto-Review](pr-auto-review.md) | `pull_request` | Medium | High | +| [Dependabot Auto-Merge](dependabot-auto-merge.md) | `pull_request` | Low | Medium | +| [Stale Issue Management](stale-issues.md) | `schedule` | Low | Medium | + +--- + +## Foundation Patterns + +Patterns that make AI more effective. + +| Pattern | Purpose | Effort | Impact | +|---------|---------|--------|--------| +| [Layered Architecture](layered-architecture.md) | Code structure AI can reason about | Low | Medium | +| [Security Patterns](security-patterns.md) | Practical protection | Low | Medium | +| [Testing Patterns](testing-patterns.md) | Test pyramid approach | Medium | High | + +--- + +## Adoption Matrix + +!!! note "Section Summary" + Decision tree for which patterns to adopt based on your situation. Pain point → recommended pattern mapping. Effort/impact quadrant visualization. + +--- + +## Pattern Dependencies + +```mermaid +flowchart TD + CBA[Codebase Agent] --> SR[Self-Review] + CBA --> MEM[Memory System] + CBA --> AQE[Autonomous Quality] + + AQE --> ITP[Issue-to-PR] + SR --> ITP + + ITP --> PAR[PR Auto-Review] + + LA[Layered Architecture] -.-> CBA + SEC[Security Patterns] -.-> CBA + TEST[Testing Patterns] -.-> AQE +``` + +Solid arrows: recommended order. Dashed arrows: optional dependencies. + +--- + +## Quick Reference + +!!! note "Section Summary" + One-page cheat sheet of all patterns with key commands and file paths. Printable format. diff --git a/docs/patterns/issue-to-pr.md b/docs/patterns/issue-to-pr.md new file mode 100644 index 0000000..da2bfd7 --- /dev/null +++ b/docs/patterns/issue-to-pr.md @@ -0,0 +1,74 @@ +# Issue-to-PR Automation + +**Convert well-defined issues to draft PRs automatically.** + +--- + +## Overview + +!!! note "Section Summary" + When a well-defined issue is created, AI analyzes it and creates a draft PR. Reduces the 20-minute PR ceremony for 2-minute fixes. Human reviews the draft, not the initial work. + +--- + +## Quick Start + +!!! note "Section Summary" + Copy the workflow YAML. Configure secrets (ANTHROPIC_API_KEY). Create a test issue. See the draft PR appear. + +--- + +## How It Works + +```mermaid +flowchart TD + A[Issue Opened] --> B{Well-defined?} + B -->|No| C[Request Clarification] + B -->|Yes| D[Analyze Issue] + D --> E[Self-Review Analysis] + E --> F[Create Branch] + F --> G[Create Draft PR] + G --> H[Link to Issue] +``` + +--- + +## Risk Categories + +!!! note "Section Summary" + Low risk (auto-fix eligible): formatting, linting, unused imports. Medium risk (PR only): refactoring, test additions. High risk (report only): breaking changes, security. How to configure each. + +--- + +## Workflow YAML + +!!! note "Section Summary" + Complete workflow file with annotations. Trigger conditions. Permissions required. Environment variables. + +--- + +## Safety Gates + +!!! note "Section Summary" + Draft PR only (requires human merge). AI analysis step with self-review. Clarification requests for unclear issues. How to add custom gates. + +--- + +## Customization + +!!! note "Section Summary" + Custom labels for different risk levels. Custom analysis prompts. Integration with project boards. Slack notifications. + +--- + +## Troubleshooting + +!!! note "Section Summary" + Common issues: workflow doesn't trigger, AI creates wrong PR, permissions errors. Solutions for each. + +--- + +## Related Patterns + +- [Self-Review Reflection](self-review-reflection.md) - AI reviews its own analysis +- [PR Auto-Review](pr-auto-review.md) - AI reviews the resulting PR diff --git a/docs/patterns/layered-architecture.md b/docs/patterns/layered-architecture.md new file mode 100644 index 0000000..bedc966 --- /dev/null +++ b/docs/patterns/layered-architecture.md @@ -0,0 +1,69 @@ +# Layered Architecture + +**Code structure AI can reason about effectively.** + +--- + +## Overview + +!!! note "Section Summary" + AI assistants struggle with spaghetti code. Clear layer boundaries help AI make better decisions. Four layers: API, Service, Model, Core. Dependency rule: higher depends on lower, never reverse. + +--- + +## Quick Start + +!!! note "Section Summary" + Example directory structure. What goes in each layer. How to reference in CBA context files. + +--- + +## The Four Layers + +### API Layer + +!!! note "Section Summary" + Route handlers, request/response models, HTTP status codes, OpenAPI documentation. No business logic here. + +### Service Layer + +!!! note "Section Summary" + Business logic, CRUD operations, orchestration. No HTTP concerns, no database queries directly. + +### Model Layer + +!!! note "Section Summary" + Pydantic models, field validation, sanitization, serialization. Data structures and their rules. + +### Core Layer + +!!! note "Section Summary" + Configuration, security utilities, logging, shared utilities. Cross-cutting concerns. + +--- + +## Dependency Rule + +```mermaid +flowchart TD + API[API Layer] --> Service[Service Layer] + Service --> Model[Model Layer] + Model --> Core[Core Layer] +``` + +!!! note "Section Summary" + Why the rule matters. How to enforce it. What to do when you need to break it. + +--- + +## AI Benefits + +!!! note "Section Summary" + Predictable AI outputs. Easier testing. Safer refactoring. How to describe layers in context files. + +--- + +## Related Patterns + +- [Security Patterns](security-patterns.md) - Where validation happens in layers +- [Testing Patterns](testing-patterns.md) - How to test each layer diff --git a/docs/patterns/pr-auto-review.md b/docs/patterns/pr-auto-review.md new file mode 100644 index 0000000..e4accfa --- /dev/null +++ b/docs/patterns/pr-auto-review.md @@ -0,0 +1,56 @@ +# PR Auto-Review + +**AI-powered code review on every pull request.** + +--- + +## Overview + +!!! note "Section Summary" + When any PR is opened or updated, AI reviews the code and posts structured feedback. Catches obvious issues before human time is spent. Severity levels: CRITICAL, WARNING, GOOD. + +--- + +## Quick Start + +!!! note "Section Summary" + Copy the workflow YAML. Configure secrets. Open a test PR. See the AI review comment appear. + +--- + +## How It Works + +```mermaid +flowchart TD + A[PR Opened/Updated] --> B[AI Reviews Code] + B --> C[Self-Review Findings] + C --> D[Post Review Comment] +``` + +--- + +## Review Format + +!!! note "Section Summary" + Structured output format with emojis for quick scanning. CRITICAL (must fix), WARNING (should consider), GOOD (positive observations). Examples of each. + +--- + +## Workflow YAML + +!!! note "Section Summary" + Complete workflow file. Trigger on opened and synchronize. Review prompt with focus areas. Comment posting. + +--- + +## Customization + +!!! note "Section Summary" + Custom review criteria. Different prompts for different file types. Blocking vs commenting only. Integration with required reviews. + +--- + +## Related Patterns + +- [Issue-to-PR](issue-to-pr.md) - Source of PRs to review +- [Multi-Agent Code Review](multi-agent-code-review.md) - Multiple specialized reviewers diff --git a/docs/patterns/security-patterns.md b/docs/patterns/security-patterns.md new file mode 100644 index 0000000..45c2203 --- /dev/null +++ b/docs/patterns/security-patterns.md @@ -0,0 +1,59 @@ +# Security Patterns + +**Practical protection without over-engineering.** + +--- + +## Overview + +!!! note "Section Summary" + Philosophy: "Validate at boundaries, trust internal code." Most security bugs come from unvalidated user input, hardcoded secrets, and injection attacks. Focus on actual attack vectors. + +--- + +## Quick Start + +!!! note "Section Summary" + Copy security context file. Add Pydantic validation to API models. Move secrets to environment variables. Done. + +--- + +## Input Validation + +!!! note "Section Summary" + Validate all request payloads with Pydantic. Sanitization in model validators. Internal code trusts validated data. Examples of validation patterns. + +--- + +## Sanitization Functions + +!!! note "Section Summary" + sanitize_string() - remove control characters, trim whitespace. validate_slug() - ensure URL-safe identifiers. When to use each. + +--- + +## Secrets Management + +!!! note "Section Summary" + Environment variables only. .env files never committed. Pydantic Settings for config. Container secrets. + +--- + +## What We Don't Do + +!!! note "Section Summary" + No security theater. No excessive validation everywhere. No complex encryption for non-sensitive data. Why less is more. + +--- + +## AI Integration + +!!! note "Section Summary" + How to describe security rules in context files. What the CBA should check. Automated security review in PRs. + +--- + +## Related Patterns + +- [Layered Architecture](layered-architecture.md) - Where security boundaries live +- [PR Auto-Review](pr-auto-review.md) - Automated security checks diff --git a/docs/patterns/stale-issues.md b/docs/patterns/stale-issues.md new file mode 100644 index 0000000..82204ce --- /dev/null +++ b/docs/patterns/stale-issues.md @@ -0,0 +1,65 @@ +# Stale Issue Management + +**Clean up inactive issues automatically.** + +--- + +## Overview + +!!! note "Section Summary" + Issues inactive for 30+ days get labeled stale. After 7 more days of inactivity, they close automatically. Exempt labels protect important issues. Keeps backlog clean without manual triage. + +--- + +## Quick Start + +!!! note "Section Summary" + Copy the workflow YAML. Configure exempt labels. Run manually to test. Watch stale issues get cleaned up. + +--- + +## How It Works + +```mermaid +flowchart TD + A[Weekly Schedule] --> B[Find Inactive Issues] + B --> C[Add Stale Label] + C --> D[Wait 7 Days] + D --> E{Activity?} + E -->|Yes| F[Remove Stale Label] + E -->|No| G[Close Issue] +``` + +--- + +## Configuration + +!!! note "Section Summary" + Inactivity threshold (default: 30 days). Warning period (default: 7 days). Stale label name. Warning message customization. + +--- + +## Exempt Labels + +!!! note "Section Summary" + Which labels prevent closure: pinned, security, bug. How to add custom exempt labels. When to use exempt vs just commenting. + +--- + +## Workflow YAML + +!!! note "Section Summary" + Complete workflow file using actions/stale. Schedule configuration. Issue and PR settings. Exempt labels. + +--- + +## Customization + +!!! note "Section Summary" + Different thresholds for issues vs PRs. Custom messages. Integration with project boards. Metrics tracking. + +--- + +## Related Patterns + +- [Dependabot Auto-Merge](dependabot-auto-merge.md) - Another proactive cleanup pattern diff --git a/docs/patterns/testing-patterns.md b/docs/patterns/testing-patterns.md new file mode 100644 index 0000000..a220b7d --- /dev/null +++ b/docs/patterns/testing-patterns.md @@ -0,0 +1,59 @@ +# Testing Patterns + +**Test pyramid approach with clear responsibilities.** + +--- + +## Overview + +!!! note "Section Summary" + Three levels: unit (many, fast), integration (some, medium), E2E (few, slow). Each level has clear responsibilities. 80%+ coverage target without chasing 100%. + +--- + +## Quick Start + +!!! note "Section Summary" + Copy testing context file. Set up tests/ directory structure. Configure pytest. Run first tests. + +--- + +## Unit Tests + +!!! note "Section Summary" + Test service layer in isolation. Mock external dependencies. Arrange-Act-Assert pattern. Location: tests/unit/. What to test, what not to test. + +--- + +## Integration Tests + +!!! note "Section Summary" + Test API endpoints with TestClient. Real request/response cycle. Database fixtures if applicable. Location: tests/integration/. When integration tests are better than unit tests. + +--- + +## E2E Tests + +!!! note "Section Summary" + Test complete workflows. CBA automation scenarios. Location: tests/e2e/. Why to keep these minimal. + +--- + +## Coverage Philosophy + +!!! note "Section Summary" + Target 80%+ coverage. Focus on critical paths. Don't chase 100% (diminishing returns). How to identify critical paths. + +--- + +## AI Test Generation + +!!! note "Section Summary" + How CBA generates tests. Test patterns in context files. Review process for AI-generated tests. + +--- + +## Related Patterns + +- [Layered Architecture](layered-architecture.md) - What each test level covers +- [Autonomous Quality Enforcement](autonomous-quality-enforcement.md) - Running tests in CBA diff --git a/docs/resources/coloring-book.md b/docs/resources/coloring-book.md new file mode 100644 index 0000000..0aea54a --- /dev/null +++ b/docs/resources/coloring-book.md @@ -0,0 +1,67 @@ +# AI-Assisted Development Coloring Book + +**A visual guide to AI-assisted development patterns.** + +--- + +## Overview + +!!! note "Section Summary" + Follow-on to the SRE "Reliability Nightmares" coloring book. Same setting (Gino's restaurant), same characters (Leo, Cookie Cache), new domain (AI-assisted development). Five challenges covering core patterns. + +--- + +## The Story + +!!! note "Section Summary" + Leo's restaurant is running smoothly after SRE improvements, but his software development team is drowning. Cookie Cache returns as an AI-assisted development coach. Five days, five challenges, one transformed team. + +--- + +## The Five Challenges + +### Challenge 1: Codebase Agent + +!!! note "Section Summary" + Visual metaphor: Every waiter using different recipes vs one master recipe book. Before/after comparison. Key takeaway: consistency across all AI interactions. + +### Challenge 2: Memory System + +!!! note "Section Summary" + Visual metaphor: AI forgetting instructions each shift vs permanent kitchen reference cards. Context files as "tribal knowledge capture." Token efficiency visualization. + +### Challenge 3: Self-Review Reflection + +!!! note "Section Summary" + Visual metaphor: Chef presenting unfinished dishes vs chef tasting before serving. The reflection loop as quality control. "Self-review: Fixed [issue]" as visible process. + +### Challenge 4: Proactive GHA Workflows + +!!! note "Section Summary" + Visual metaphor: Manual everything vs automated prep work. Four automations: Issue-to-PR, PR Auto-Review, Dependabot Auto-Merge, Stale Issue cleanup. Safety gates visualization. + +### Challenge 5: Issue-to-PR (Full Cycle) + +!!! note "Section Summary" + Visual metaphor: 20-minute ceremony for 2-minute fix vs automated end-to-end. Risk categories table. The "10x productivity" payoff. + +--- + +## Download + +!!! note "Section Summary" + PDF download link. Print-friendly version. Interactive online version (if applicable). + +--- + +## Self-Assessment + +!!! note "Section Summary" + Rate your team 1-5 on each challenge. Score interpretation: beginner/advanced/expert. Recommended starting points for each level. + +--- + +## Behind the Scenes + +!!! note "Section Summary" + Link to COLORING-BOOK-SCRIPT.md for production notes. How the original SRE coloring book was created. Collaboration credits. diff --git a/docs/resources/demo-app.md b/docs/resources/demo-app.md new file mode 100644 index 0000000..b7a755a --- /dev/null +++ b/docs/resources/demo-app.md @@ -0,0 +1,51 @@ +# Demo Application + +**See AI-assisted development patterns in action.** + +--- + +## Overview + +!!! note "Section Summary" + The demo-fastapi repository is a working FastAPI application demonstrating all patterns from this reference. Not a toy example - a complete implementation you can run locally or deploy. + +--- + +## Repository + +**GitHub**: [jeremyeder/demo-fastapi](https://github.com/jeremyeder/demo-fastapi) + +--- + +## What's Included + +!!! note "Section Summary" + Working FastAPI service with CRUD endpoints. Full CBA configuration. Test suite (unit, integration, E2E). Container support (Podman/Docker). CI/CD workflows. + +--- + +## Quick Start + +!!! note "Section Summary" + Clone, install, run. API endpoints to try. How to trigger CBA workflows. Expected output for each. + +--- + +## Patterns Demonstrated + +!!! note "Section Summary" + Which patterns are implemented and where to find them in the demo. File paths for each pattern. How they interact in practice. + +--- + +## Extending the Demo + +!!! note "Section Summary" + How to add new endpoints following patterns. How to modify CBA for your needs. How to add new automations. + +--- + +## Comparing to Reference + +!!! note "Section Summary" + Reference repo = documentation-only patterns. Demo repo = working implementation. When to use which. diff --git a/docs/resources/presentation.md b/docs/resources/presentation.md new file mode 100644 index 0000000..d7a45cc --- /dev/null +++ b/docs/resources/presentation.md @@ -0,0 +1,47 @@ +# Presentation Document + +**Structured content for NotebookLM podcast generation.** + +--- + +## Overview + +!!! note "Section Summary" + A 9-feature presentation designed for NotebookLM to generate podcasts. Target audience: principal engineers evaluating AI-assisted development. Format: problem/solution/payoff for each feature. + +--- + +## Features Covered + +| # | Feature | Category | +|---|---------|----------| +| 1 | Codebase Agent (CBA) | Agent Behavior | +| 2 | Memory System | Agent Behavior | +| 3 | Issue-to-PR Automation | GHA Automation | +| 4 | Layered Architecture | Foundation | +| 5 | Security Patterns | Foundation | +| 6 | Testing Patterns | Foundation | +| 7 | CI/CD for Documentation | Foundation | +| 8 | Self-Review Reflection | Agent Behavior | +| 9 | Proactive GHA Workflows | GHA Automation | + +--- + +## Download + +!!! note "Section Summary" + Link to PRESENTATION-ambient-code-reference.md. Markdown format for NotebookLM ingestion. PDF version for sharing. + +--- + +## Using with NotebookLM + +!!! note "Section Summary" + How to upload to NotebookLM. Recommended prompts for podcast generation. Sample output audio (if available). + +--- + +## Presentation Outline + +!!! note "Section Summary" + For each of the 9 features: What it is, problem it solves, how it works, benefits for principal engineers. Adoption guidance. Common objections and responses. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..fe2660e --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,105 @@ +# MkDocs configuration for Ambient Code Reference Repository +site_name: Ambient Code Reference +site_description: AI-assisted development patterns and best practices +site_author: Jeremy Eder +site_url: https://jeremyeder.github.io/reference/ + +# Repository +repo_name: jeremyeder/reference +repo_url: https://github.com/jeremyeder/reference +edit_uri: edit/main/docs/ + +# Theme +theme: + name: material + palette: + - scheme: default + primary: indigo + accent: indigo + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: indigo + accent: indigo + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - navigation.instant + - navigation.tracking + - navigation.sections + - navigation.expand + - navigation.top + - search.suggest + - search.highlight + - content.code.copy + - content.action.edit + +# Extensions +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - tables + - toc: + permalink: true + +# Plugins +plugins: + - search + - mermaid2 + +# Navigation +nav: + - Home: index.md + - Getting Started: + - Quickstart: quickstart.md + - Installation: getting-started/installation.md + - Your First CBA: getting-started/first-cba.md + - Patterns: + - Overview: patterns/index.md + - Agent Behavior: + - Codebase Agent (CBA): patterns/codebase-agent.md + - Self-Review Reflection: patterns/self-review-reflection.md + - Autonomous Quality Enforcement: patterns/autonomous-quality-enforcement.md + - Multi-Agent Code Review: patterns/multi-agent-code-review.md + - GHA Automation: + - Overview: patterns/gha-automation-patterns.md + - Issue-to-PR: patterns/issue-to-pr.md + - PR Auto-Review: patterns/pr-auto-review.md + - Dependabot Auto-Merge: patterns/dependabot-auto-merge.md + - Stale Issue Management: patterns/stale-issues.md + - Architecture: + - Layered Architecture: patterns/layered-architecture.md + - Security Patterns: patterns/security-patterns.md + - Testing Patterns: patterns/testing-patterns.md + - Reference: + - Architecture: architecture.md + - API Patterns: api-reference.md + - ADR Template: adr/template.md + - Tutorial: tutorial.md + - Resources: + - Coloring Book: resources/coloring-book.md + - Presentation: resources/presentation.md + - Demo Application: resources/demo-app.md + +# Extra +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/jeremyeder + generator: false + +# Copyright +copyright: Copyright © 2024-2026 Jeremy Eder From adcd1c3ef0bc5ad95b79bede5ea90a8151dde685 Mon Sep 17 00:00:00 2001 From: Jeremy Eder Date: Mon, 5 Jan 2026 02:55:01 -0500 Subject: [PATCH 2/2] chore: remove coloring book references from docs --- docs/index.md | 1 - docs/resources/coloring-book.md | 67 --------------------------------- mkdocs.yml | 1 - 3 files changed, 69 deletions(-) delete mode 100644 docs/resources/coloring-book.md diff --git a/docs/index.md b/docs/index.md index 74e933c..4751c02 100644 --- a/docs/index.md +++ b/docs/index.md @@ -129,7 +129,6 @@ Enabling patterns that make AI more effective. | Resource | Format | Purpose | |----------|--------|---------| -| [Coloring Book](resources/coloring-book.md) | PDF/Interactive | Visual guide to concepts (follow-on to SRE Coloring Book) | | [Presentation](resources/presentation.md) | Markdown | NotebookLM podcast generation, 9 features explained | | [Demo Application](resources/demo-app.md) | GitHub Repo | Working FastAPI example | diff --git a/docs/resources/coloring-book.md b/docs/resources/coloring-book.md deleted file mode 100644 index 0aea54a..0000000 --- a/docs/resources/coloring-book.md +++ /dev/null @@ -1,67 +0,0 @@ -# AI-Assisted Development Coloring Book - -**A visual guide to AI-assisted development patterns.** - ---- - -## Overview - -!!! note "Section Summary" - Follow-on to the SRE "Reliability Nightmares" coloring book. Same setting (Gino's restaurant), same characters (Leo, Cookie Cache), new domain (AI-assisted development). Five challenges covering core patterns. - ---- - -## The Story - -!!! note "Section Summary" - Leo's restaurant is running smoothly after SRE improvements, but his software development team is drowning. Cookie Cache returns as an AI-assisted development coach. Five days, five challenges, one transformed team. - ---- - -## The Five Challenges - -### Challenge 1: Codebase Agent - -!!! note "Section Summary" - Visual metaphor: Every waiter using different recipes vs one master recipe book. Before/after comparison. Key takeaway: consistency across all AI interactions. - -### Challenge 2: Memory System - -!!! note "Section Summary" - Visual metaphor: AI forgetting instructions each shift vs permanent kitchen reference cards. Context files as "tribal knowledge capture." Token efficiency visualization. - -### Challenge 3: Self-Review Reflection - -!!! note "Section Summary" - Visual metaphor: Chef presenting unfinished dishes vs chef tasting before serving. The reflection loop as quality control. "Self-review: Fixed [issue]" as visible process. - -### Challenge 4: Proactive GHA Workflows - -!!! note "Section Summary" - Visual metaphor: Manual everything vs automated prep work. Four automations: Issue-to-PR, PR Auto-Review, Dependabot Auto-Merge, Stale Issue cleanup. Safety gates visualization. - -### Challenge 5: Issue-to-PR (Full Cycle) - -!!! note "Section Summary" - Visual metaphor: 20-minute ceremony for 2-minute fix vs automated end-to-end. Risk categories table. The "10x productivity" payoff. - ---- - -## Download - -!!! note "Section Summary" - PDF download link. Print-friendly version. Interactive online version (if applicable). - ---- - -## Self-Assessment - -!!! note "Section Summary" - Rate your team 1-5 on each challenge. Score interpretation: beginner/advanced/expert. Recommended starting points for each level. - ---- - -## Behind the Scenes - -!!! note "Section Summary" - Link to COLORING-BOOK-SCRIPT.md for production notes. How the original SRE coloring book was created. Collaboration credits. diff --git a/mkdocs.yml b/mkdocs.yml index fe2660e..4dd6316 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -90,7 +90,6 @@ nav: - ADR Template: adr/template.md - Tutorial: tutorial.md - Resources: - - Coloring Book: resources/coloring-book.md - Presentation: resources/presentation.md - Demo Application: resources/demo-app.md