Skip to content

Commit 0cc24ed

Browse files
jeremyederjeremyeder
authored
feat: add GitHub Pages with MkDocs documentation (#8)
* 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. * chore: remove coloring book references from docs
1 parent 47d4963 commit 0cc24ed

17 files changed

Lines changed: 1176 additions & 0 deletions

‎.github/workflows/deploy-docs.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- "docs/**"
8+
- "mkdocs.yml"
9+
- ".github/workflows/deploy-docs.yml"
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
concurrency:
18+
group: "pages"
19+
cancel-in-progress: false
20+
21+
jobs:
22+
build:
23+
runs-on: ubuntu-latest
24+
steps:
25+
- uses: actions/checkout@v4
26+
with:
27+
fetch-depth: 0
28+
29+
- name: Set up Python
30+
uses: actions/setup-python@v5
31+
with:
32+
python-version: "3.11"
33+
34+
- name: Install dependencies
35+
run: |
36+
pip install mkdocs-material mkdocs-mermaid2-plugin
37+
38+
- name: Build documentation
39+
run: mkdocs build --strict
40+
41+
- name: Upload artifact
42+
uses: actions/upload-pages-artifact@v3
43+
with:
44+
path: site
45+
46+
deploy:
47+
environment:
48+
name: github-pages
49+
url: ${{ steps.deployment.outputs.page_url }}
50+
runs-on: ubuntu-latest
51+
needs: build
52+
steps:
53+
- name: Deploy to GitHub Pages
54+
id: deployment
55+
uses: actions/deploy-pages@v4

‎.markdownlint.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@
33
"MD013": false,
44
"MD033": false,
55
"MD041": false,
6+
"MD046": false,
67
"MD051": false
78
}

‎docs/getting-started/first-cba.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Your First Codebase Agent
2+
3+
**Create a CBA in 30 minutes.**
4+
5+
---
6+
7+
## Overview
8+
9+
!!! note "Section Summary"
10+
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.
11+
12+
---
13+
14+
## Step 1: Copy the Template
15+
16+
!!! note "Section Summary"
17+
Copy `.claude/` from reference repo to your project. Directory structure explanation. What each file does.
18+
19+
---
20+
21+
## Step 2: Customize the Agent Definition
22+
23+
!!! note "Section Summary"
24+
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).
25+
26+
---
27+
28+
## Step 3: Create Context Files
29+
30+
### Architecture Context
31+
32+
!!! note "Section Summary"
33+
`.claude/context/architecture.md` - describe your layers, component responsibilities, data flow. Template provided. Examples for common stacks (FastAPI, Express, Django).
34+
35+
### Security Context
36+
37+
!!! note "Section Summary"
38+
`.claude/context/security-standards.md` - your validation rules, sanitization patterns, secrets management approach. What to validate, what to trust.
39+
40+
### Testing Context
41+
42+
!!! note "Section Summary"
43+
`.claude/context/testing-patterns.md` - your test pyramid, where tests live, mocking conventions, coverage targets.
44+
45+
---
46+
47+
## Step 4: Test Your CBA
48+
49+
!!! note "Section Summary"
50+
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.
51+
52+
---
53+
54+
## Step 5: Share with Your Team
55+
56+
!!! note "Section Summary"
57+
Commit `.claude/` to your repo. Team onboarding: everyone gets the same AI behavior. Updating context files: when and how.
58+
59+
---
60+
61+
## Memory System Deep Dive
62+
63+
!!! note "Section Summary"
64+
How modular context works. Loading context on-demand. Token efficiency. When to split vs combine context files.
65+
66+
---
67+
68+
## Troubleshooting
69+
70+
!!! note "Section Summary"
71+
Common issues: AI ignores context (file not loaded), AI makes up conventions (context too vague), AI over-engineers (context too broad). Solutions for each.
72+
73+
---
74+
75+
## Next Steps
76+
77+
- [Patterns Index](../patterns/index.md) - Explore all available patterns
78+
- [Self-Review Reflection](../patterns/self-review-reflection.md) - Add quality gates to your CBA

‎docs/getting-started/installation.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Installation
2+
3+
**Set up tooling for AI-assisted development.**
4+
5+
---
6+
7+
## Prerequisites
8+
9+
!!! note "Section Summary"
10+
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.
11+
12+
---
13+
14+
## Quick Install
15+
16+
!!! note "Section Summary"
17+
One-liner install scripts for macOS/Linux. Clone reference repo, install dependencies with uv, verify setup with validation scripts.
18+
19+
---
20+
21+
## Tool-by-Tool Setup
22+
23+
### Python Environment
24+
25+
!!! note "Section Summary"
26+
Virtual environment setup with uv. Why uv over pip (speed, reliability). Verification steps.
27+
28+
### Claude CLI / API
29+
30+
!!! note "Section Summary"
31+
Claude Code installation and authentication. API key management. Verification that Claude can access your codebase.
32+
33+
### Linting Tools
34+
35+
!!! note "Section Summary"
36+
markdownlint-cli installation. Black, isort, ruff for Python. Configuration files included in reference repo.
37+
38+
### Mermaid Validation
39+
40+
!!! note "Section Summary"
41+
@mermaid-js/mermaid-cli installation. Why Mermaid validation matters for documentation CI.
42+
43+
---
44+
45+
## Verification
46+
47+
!!! note "Section Summary"
48+
Run all validation scripts to confirm installation. Expected output for each. Troubleshooting common issues.
49+
50+
---
51+
52+
## Next Steps
53+
54+
- [Your First CBA](first-cba.md) - Create your first Codebase Agent

‎docs/index.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# Ambient Code Reference
2+
3+
**AI-assisted development patterns for engineering teams.**
4+
5+
---
6+
7+
## Executive Summary
8+
9+
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?"*
10+
11+
**Key Value Propositions:**
12+
13+
1. **Consistency** - Every AI interaction follows the same process
14+
2. **Safety** - Human review gates prevent runaway automation
15+
3. **Productivity** - 10x speedup for routine tasks
16+
4. **Transferability** - Patterns work across tools and languages
17+
18+
**Approach:** Standalone patterns. Adopt what you need, skip what you don't. No prescribed sequence.
19+
20+
---
21+
22+
## What's Inside
23+
24+
### Patterns (9 Total)
25+
26+
| Pattern | Category | Effort | Impact |
27+
|---------|----------|--------|--------|
28+
| [Codebase Agent (CBA)](#cba) | Agent Behavior | Medium | High |
29+
| [Memory System](#memory) | Agent Behavior | Low | Medium |
30+
| [Self-Review Reflection](#self-review) | Agent Behavior | Low | High |
31+
| [Issue-to-PR Automation](#issue-to-pr) | GHA Automation | High | Very High |
32+
| [PR Auto-Review](#pr-review) | GHA Automation | Medium | High |
33+
| [Dependabot Auto-Merge](#dependabot) | GHA Automation | Low | Medium |
34+
| [Stale Issue Management](#stale) | GHA Automation | Low | Medium |
35+
| [Layered Architecture](#architecture) | Foundation | Low | Medium |
36+
| [Security Patterns](#security) | Foundation | Low | Medium |
37+
38+
### Quick Start Paths
39+
40+
=== "I want consistent AI assistance"
41+
42+
Start with [Codebase Agent](patterns/codebase-agent.md) - one file that defines how AI works in your codebase.
43+
44+
=== "AI keeps forgetting my conventions"
45+
46+
Start with [Memory System](getting-started/first-cba.md#memory-system) - modular context files that persist across sessions.
47+
48+
=== "Routine fixes take too long"
49+
50+
Start with [Issue-to-PR Automation](patterns/issue-to-pr.md) - convert well-defined issues to PRs automatically.
51+
52+
=== "I want to see it working first"
53+
54+
Check out the [demo-fastapi](https://github.com/jeremyeder/demo-fastapi) repository for a working example.
55+
56+
---
57+
58+
## Documentation Structure
59+
60+
### Getting Started
61+
62+
| Section | Purpose | Time |
63+
|---------|---------|------|
64+
| [Quickstart](quickstart.md) | 5-minute introduction to AI-assisted development | 5 min |
65+
| [Installation](getting-started/installation.md) | Set up tooling and dependencies | 15 min |
66+
| [Your First CBA](getting-started/first-cba.md) | Create your first Codebase Agent | 30 min |
67+
68+
**What you'll learn:** How to copy the `.claude/` directory to your project and customize it for your tech stack.
69+
70+
---
71+
72+
### Patterns
73+
74+
#### Agent Behavior Patterns
75+
76+
How AI agents behave during development.
77+
78+
| Pattern | What It Does | Section Summary |
79+
|---------|--------------|-----------------|
80+
| [Codebase Agent](patterns/codebase-agent.md) | Defines AI behavior, capabilities, and guardrails | Agent definition structure, autonomy levels, workflow examples, capability boundaries |
81+
| [Self-Review Reflection](patterns/self-review-reflection.md) | Agent reviews own work before presenting | Reflection loop, checklist criteria, implementation prompts, anti-patterns |
82+
| [Autonomous Quality](patterns/autonomous-quality-enforcement.md) | Validates code quality before delivery | Lint loops, test verification, error budgets |
83+
| [Multi-Agent Review](patterns/multi-agent-code-review.md) | Multiple specialized agents review in parallel | Agent roles, consensus mechanisms, conflict resolution |
84+
85+
#### GHA Automation Patterns
86+
87+
Proactive CI/CD workflows.
88+
89+
| Pattern | Trigger | Section Summary |
90+
|---------|---------|-----------------|
91+
| [Issue-to-PR](patterns/issue-to-pr.md) | `issues.opened` | Requirements analysis, draft PR creation, risk categories, safety gates |
92+
| [PR Auto-Review](patterns/pr-auto-review.md) | `pull_request` | AI review format, severity levels, when to block vs comment |
93+
| [Dependabot Auto-Merge](patterns/dependabot-auto-merge.md) | `pull_request` | Patch vs minor/major, CI requirements, safety conditions |
94+
| [Stale Issues](patterns/stale-issues.md) | `schedule` | Inactivity thresholds, warning periods, exempt labels |
95+
96+
#### Foundation Patterns
97+
98+
Enabling patterns that make AI more effective.
99+
100+
| Pattern | Purpose | Section Summary |
101+
|---------|---------|-----------------|
102+
| [Layered Architecture](patterns/layered-architecture.md) | Code structure AI can reason about | Four layers, dependency rules, component responsibilities |
103+
| [Security Patterns](patterns/security-patterns.md) | Practical protection without over-engineering | Boundary validation, sanitization, secrets management |
104+
| [Testing Patterns](patterns/testing-patterns.md) | Test pyramid approach | Unit/integration/E2E, coverage targets, AI test generation |
105+
106+
---
107+
108+
### Reference
109+
110+
| Section | Purpose | Contents |
111+
|---------|---------|----------|
112+
| [Architecture](architecture.md) | Deep dive into architecture patterns | Data flow diagrams, layer boundaries, extension points |
113+
| [API Patterns](api-reference.md) | API design for AI-assisted development | Request/response patterns, error handling, OpenAPI |
114+
| [ADR Template](adr/template.md) | Decision record scaffolding | YYYYMMDD-title.md format, context/decision/consequences |
115+
116+
---
117+
118+
### Tutorial
119+
120+
| Section | Purpose | Time |
121+
|---------|---------|------|
122+
| [Full Tutorial](tutorial.md) | Step-by-step implementation guide | 2-4 hours |
123+
124+
**What you'll build:** A complete AI-assisted development setup from scratch, including CBA, memory system, and GHA automations.
125+
126+
---
127+
128+
### Resources
129+
130+
| Resource | Format | Purpose |
131+
|----------|--------|---------|
132+
| [Presentation](resources/presentation.md) | Markdown | NotebookLM podcast generation, 9 features explained |
133+
| [Demo Application](resources/demo-app.md) | GitHub Repo | Working FastAPI example |
134+
135+
---
136+
137+
## Navigation Guide
138+
139+
```mermaid
140+
flowchart TD
141+
A[Start Here] --> B{What do you need?}
142+
B -->|Understand the concepts| C[Quickstart]
143+
B -->|See it working| D[Demo App]
144+
B -->|Implement patterns| E[Tutorial]
145+
B -->|Reference specific pattern| F[Patterns Index]
146+
147+
C --> G[Your First CBA]
148+
D --> G
149+
E --> G
150+
F --> H[Choose Pattern]
151+
152+
G --> I[Production Setup]
153+
H --> I
154+
```
155+
156+
---
157+
158+
## Design Principles
159+
160+
1. **Standalone patterns** - No dependencies between patterns. Adopt one without adopting others.
161+
2. **Copy-paste ready** - All configurations are complete and ready to customize.
162+
3. **Human-in-the-loop** - AI assists, humans decide. Safety gates everywhere.
163+
4. **Vendor-agnostic** - Patterns work with any AI tool or none at all.
164+
5. **Minimal ceremony** - Start small, add complexity only when needed.
165+
166+
---
167+
168+
## Who This Is For
169+
170+
| Role | Benefit |
171+
|------|---------|
172+
| **Principal Engineers** | Evaluate AI adoption strategy with battle-tested patterns |
173+
| **Team Leads** | Implement consistent AI workflows across your team |
174+
| **Senior Developers** | Get productivity gains without sacrificing quality |
175+
| **Junior Developers** | Get senior-level AI assistance with guardrails |
176+
177+
---
178+
179+
## Quick Links
180+
181+
- **GitHub Repository**: [jeremyeder/reference](https://github.com/jeremyeder/reference)
182+
- **Demo Application**: [jeremyeder/demo-fastapi](https://github.com/jeremyeder/demo-fastapi)
183+
- **Original SRE Coloring Book**: [red.ht/sre-coloring-book](https://red.ht/sre-coloring-book)
184+
185+
---
186+
187+
*"Stable, Secure, Performant, and Boring" - the goal is to make AI assistance invisible through excellence.*

0 commit comments

Comments
 (0)