Skip to content

Commit 885c342

Browse files
jeremyederjeremyeder
authored
docs: condense pattern docs by ~73% (#11)
* docs: condense pattern docs by ~73% - Replace stub content with full documentation - Cut verbose sections (Complete Workflow, Customization, etc.) - Convert troubleshooting to tables - Use tables throughout for scannability - Remove redundant code examples Before: 3282 lines | After: 880 lines * fix: resolve markdown lint errors in PRESENTATION file
1 parent ae15cd0 commit 885c342

10 files changed

Lines changed: 559 additions & 278 deletions

‎PRESENTATION-ambient-code-reference.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ This reference repository provides useful patterns you can review / adopt increm
2929
A pre-configured AI agent definition that knows how to work with your codebase safely and consistently.
3030
The idea behind a CBA is to use an agent to eventually proxy 100% of the interaction with a codebase through this agent.
3131

32-
**cba = codebase system prompt**
32+
(cba = codebase system prompt)
3333

3434
### The Problem It Solves
3535

@@ -107,7 +107,7 @@ What's important is that your team has collected and agrees upon the context sin
107107

108108
### Loading Context On-Demand
109109

110-
Instead of loading everything, you load what's relevant.
110+
Instead of loading everything, you load what's relevant.
111111

112112
"Load the security-standards context and help me review this authentication PR"
113113

@@ -131,7 +131,7 @@ For relation between elements, load these files into e.g. the local Anthropic Me
131131
### Issue-to-PR Overview
132132

133133
A pattern where well-defined GitHub issues can be automatically converted into pull requests by the CBA.
134-
Example: https://github.com/ambient-code/agentready/pull/242
134+
Example: <https://github.com/ambient-code/agentready/pull/242>
135135

136136
### Routine Fix Overhead
137137

‎docs/patterns/codebase-agent.md‎

Lines changed: 49 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -4,73 +4,83 @@
44

55
---
66

7-
## Overview
8-
9-
!!! note "Section Summary"
10-
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.
11-
12-
---
13-
147
## Quick Start
158

16-
!!! note "Section Summary"
17-
Copy-paste the CBA definition from `.claude/agents/codebase-agent.md`. Minimal customization: your linting commands, your test commands. Done in 15 minutes.
9+
Create `.claude/agents/codebase-agent.md`:
1810

11+
```markdown
12+
---
13+
name: codebase-agent
14+
description: Autonomous codebase operations for [your-project]
1915
---
2016

21-
## Agent Definition Structure
22-
23-
### Capability Boundaries
24-
25-
!!! note "Section Summary"
26-
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.
27-
28-
### Workflow Definitions
17+
# Codebase Agent
2918

30-
!!! note "Section Summary"
31-
Step-by-step processes for common tasks: issue-to-PR, code review, refactoring. Template workflows provided. How to customize for your process.
19+
## Quality Gates (run before presenting code)
20+
1. Lint: `npm run lint`
21+
2. Test: `npm test`
22+
3. Fix failures before showing code
3223

33-
### Quality Gates
24+
## Safety Rules
25+
- NEVER commit directly to main
26+
- ALWAYS create feature branches
27+
- ASK before breaking changes
28+
```
3429

35-
!!! note "Section Summary"
36-
Linting, testing, and review requirements. Which tools to run, in what order. What constitutes a passing gate. Error handling.
30+
---
3731

38-
### Safety Guardrails
32+
## Agent Structure
3933

40-
!!! note "Section Summary"
41-
When to stop and ask for human input. Risk categories: low/medium/high. Examples of each. How to configure alert thresholds.
34+
| Section | Purpose | Example |
35+
|---------|---------|---------|
36+
| **Capability Boundaries** | What agent can do autonomously | Formatting: auto. Architecture: human approval |
37+
| **Workflow Definitions** | Step-by-step processes | Issue→PR, code review steps |
38+
| **Quality Gates** | Tools to run, in order | `black . && isort . && pytest` |
39+
| **Safety Guardrails** | When to stop and ask | >10 files changed, security code, DB schema |
4240

4341
---
4442

4543
## Autonomy Levels
4644

47-
!!! note "Section Summary"
48-
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.
45+
| Level | Behavior | Use When |
46+
|-------|----------|----------|
47+
| **1: Conservative** | Create PRs only, wait for human approval | Starting out, high-risk projects |
48+
| **2: Moderate** | Auto-merge docs/deps/lint fixes after CI passes | Established trust, good test coverage |
49+
| **3: Aggressive** | Auto-deploy after tests pass | Mature codebase, comprehensive CI |
4950

50-
---
51+
Start at Level 1. Graduate as you build trust.
5152

52-
## Memory System Integration
53+
---
5354

54-
!!! note "Section Summary"
55-
How CBA uses context files from `.claude/context/`. Loading context on-demand. When to reference which context file.
55+
## Memory System
5656

57-
---
57+
Context files in `.claude/context/` provide persistent knowledge:
5858

59-
## Real-World Examples
59+
```text
60+
.claude/
61+
├── agents/
62+
│ └── codebase-agent.md
63+
└── context/
64+
├── architecture.md # Code structure patterns
65+
├── security-standards.md
66+
└── testing-patterns.md
67+
```
6068

61-
!!! note "Section Summary"
62-
CBA configurations for different stacks: Python/FastAPI, TypeScript/Express, Go. What's different, what's the same.
69+
Reference in your agent: "Load `.claude/context/architecture.md` for code placement decisions."
6370

6471
---
6572

6673
## Troubleshooting
6774

68-
!!! note "Section Summary"
69-
Common issues: agent ignores boundaries, agent is too conservative, agent makes up conventions. Solutions for each.
75+
| Problem | Fix |
76+
|---------|-----|
77+
| Agent ignores boundaries | Make rules explicit: "NEVER delete files without asking" |
78+
| Agent too conservative | Define allowed autonomous actions explicitly |
79+
| Agent invents conventions | Provide code examples in context files |
7080

7181
---
7282

7383
## Related Patterns
7484

75-
- [Self-Review Reflection](self-review-reflection.md) - Add quality gates to CBA output
76-
- [Memory System](../getting-started/first-cba.md) - Persistent context across sessions
85+
- [Self-Review Reflection](self-review-reflection.md)
86+
- [Autonomous Quality Enforcement](autonomous-quality-enforcement.md)

‎docs/patterns/dependabot-auto-merge.md‎

Lines changed: 60 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -4,54 +4,90 @@
44

55
---
66

7-
## Overview
8-
9-
!!! note "Section Summary"
10-
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.
11-
12-
---
13-
147
## Quick Start
158

16-
!!! note "Section Summary"
17-
Copy the workflow YAML. No additional secrets needed. Enable Dependabot in your repo. Watch patch updates auto-merge.
9+
Create `.github/workflows/dependabot-auto-merge.yml`:
10+
11+
```yaml
12+
name: Dependabot Auto-Merge
13+
14+
on:
15+
pull_request:
16+
types: [opened, synchronize, reopened]
17+
18+
permissions:
19+
contents: write
20+
pull-requests: write
21+
22+
jobs:
23+
auto-merge:
24+
if: github.actor == 'dependabot[bot]'
25+
runs-on: ubuntu-latest
26+
steps:
27+
- name: Fetch metadata
28+
id: metadata
29+
uses: dependabot/fetch-metadata@v2
30+
with:
31+
github-token: ${{ secrets.GITHUB_TOKEN }}
32+
33+
- name: Auto-merge patch updates
34+
if: steps.metadata.outputs.update-type == 'version-update:semver-patch'
35+
run: gh pr merge --auto --squash "$PR_URL"
36+
env:
37+
PR_URL: ${{ github.event.pull_request.html_url }}
38+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
39+
```
40+
41+
Enable Dependabot in `.github/dependabot.yml`. Set up branch protection requiring CI to pass.
1842

1943
---
2044

2145
## How It Works
2246

2347
```mermaid
2448
flowchart TD
25-
A[Dependabot PR] --> B{Patch Version?}
26-
B -->|No| C[Require Human Review]
27-
B -->|Yes| D{CI Passes?}
28-
D -->|No| C
29-
D -->|Yes| E[Auto-Merge]
49+
A[Dependabot PR] --> B{Author is dependabot?}
50+
B -->|No| C[Normal Review]
51+
B -->|Yes| D[Fetch Metadata]
52+
D --> E{Patch Version?}
53+
E -->|No| C
54+
E -->|Yes| F{CI Passes?}
55+
F -->|No| C
56+
F -->|Yes| G[Auto-Merge]
3057
```
3158

3259
---
3360

34-
## Safety Conditions
61+
## Update Types
3562

36-
!!! note "Section Summary"
37-
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.
63+
| Type | Value | Risk | Default Action |
64+
|------|-------|------|----------------|
65+
| Patch | `version-update:semver-patch` | Low | Auto-merge |
66+
| Minor | `version-update:semver-minor` | Medium | Human review |
67+
| Major | `version-update:semver-major` | High | Human review |
3868

3969
---
4070

41-
## Workflow YAML
71+
## Options
4272

43-
!!! note "Section Summary"
44-
Complete workflow file. Dependabot metadata action. Conditional auto-merge. Squash and delete branch.
73+
| Option | Add to workflow |
74+
|--------|-----------------|
75+
| **Also merge minor** | Add step with `if: steps.metadata.outputs.update-type == 'version-update:semver-minor'` |
76+
| **Only dev deps** | Add `&& steps.metadata.outputs.dependency-type == 'direct:development'` |
77+
| **Exclude packages** | Check `steps.metadata.outputs.dependency-names` doesn't contain package |
4578

4679
---
4780

48-
## Customization
81+
## Troubleshooting
4982

50-
!!! note "Section Summary"
51-
Auto-merge minor versions too. Exclude specific packages. Custom merge strategy. Notifications.
83+
| Problem | Fix |
84+
|---------|-----|
85+
| Auto-merge not triggering | Use `pull_request_target` event for fork PRs |
86+
| Permission denied | Add `contents: write` permission |
87+
| Doesn't wait for CI | Enable branch protection with required status checks |
5288

5389
---
5490

5591
## Related Patterns
5692

57-
- [Stale Issue Management](stale-issues.md) - Another proactive cleanup pattern
93+
- [Stale Issue Management](stale-issues.md)

‎docs/patterns/index.md‎

Lines changed: 42 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,50 @@
11
# Patterns Index
22

3-
**All AI-assisted development patterns in one place.**
3+
Each pattern is standalone—adopt what you need.
44

55
---
66

7-
## Overview
7+
## Agent Behavior
88

9-
!!! note "Section Summary"
10-
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.
9+
| Pattern | Effort | Impact |
10+
|---------|--------|--------|
11+
| [Codebase Agent](codebase-agent.md) | Medium | High |
12+
| [Self-Review Reflection](self-review-reflection.md) | Low | High |
13+
| [Autonomous Quality Enforcement](autonomous-quality-enforcement.md) | Medium | High |
14+
| [Multi-Agent Code Review](multi-agent-code-review.md) | High | Very High |
1115

1216
---
1317

14-
## Agent Behavior Patterns
18+
## GHA Automation
1519

16-
How AI agents behave during development.
17-
18-
| Pattern | Effort | Impact | Description |
19-
|---------|--------|--------|-------------|
20-
| [Codebase Agent](codebase-agent.md) | Medium | High | Single source of truth for AI behavior |
21-
| [Self-Review Reflection](self-review-reflection.md) | Low | High | Agent reviews own work before presenting |
22-
| [Autonomous Quality Enforcement](autonomous-quality-enforcement.md) | Medium | High | Validate code before delivery |
23-
| [Multi-Agent Code Review](multi-agent-code-review.md) | High | Very High | Parallel specialized reviews |
24-
25-
---
26-
27-
## GHA Automation Patterns
28-
29-
Proactive CI/CD workflows that reduce toil.
30-
31-
| Pattern | Trigger | Effort | Impact |
32-
|---------|---------|--------|--------|
33-
| [Issue-to-PR](issue-to-pr.md) | `issues.opened` | High | Very High |
34-
| [PR Auto-Review](pr-auto-review.md) | `pull_request` | Medium | High |
35-
| [Dependabot Auto-Merge](dependabot-auto-merge.md) | `pull_request` | Low | Medium |
36-
| [Stale Issue Management](stale-issues.md) | `schedule` | Low | Medium |
20+
| Pattern | Trigger | Effort |
21+
|---------|---------|--------|
22+
| [Issue-to-PR](issue-to-pr.md) | `issues.opened` | High |
23+
| [PR Auto-Review](pr-auto-review.md) | `pull_request` | Medium |
24+
| [Dependabot Auto-Merge](dependabot-auto-merge.md) | `pull_request` | Low |
25+
| [Stale Issue Management](stale-issues.md) | `schedule` | Low |
3726

3827
---
3928

40-
## Foundation Patterns
29+
## Foundation
4130

42-
Patterns that make AI more effective.
43-
44-
| Pattern | Purpose | Effort | Impact |
45-
|---------|---------|--------|--------|
46-
| [Layered Architecture](layered-architecture.md) | Code structure AI can reason about | Low | Medium |
47-
| [Security Patterns](security-patterns.md) | Practical protection | Low | Medium |
48-
| [Testing Patterns](testing-patterns.md) | Test pyramid approach | Medium | High |
31+
| Pattern | Purpose |
32+
|---------|---------|
33+
| [Layered Architecture](layered-architecture.md) | Code structure AI can reason about |
34+
| [Security Patterns](security-patterns.md) | Validate at boundaries |
35+
| [Testing Patterns](testing-patterns.md) | Test pyramid approach |
4936

5037
---
5138

52-
## Adoption Matrix
39+
## Start Here
5340

54-
!!! note "Section Summary"
55-
Decision tree for which patterns to adopt based on your situation. Pain point → recommended pattern mapping. Effort/impact quadrant visualization.
41+
| Pain Point | Pattern |
42+
|------------|---------|
43+
| AI gives inconsistent answers | [Codebase Agent](codebase-agent.md) |
44+
| AI misses obvious bugs | [Self-Review Reflection](self-review-reflection.md) |
45+
| PRs take forever to create | [Issue-to-PR](issue-to-pr.md) |
46+
| Code reviews are bottleneck | [PR Auto-Review](pr-auto-review.md) |
47+
| Dependency updates pile up | [Dependabot Auto-Merge](dependabot-auto-merge.md) |
5648

5749
---
5850

@@ -61,24 +53,29 @@ Patterns that make AI more effective.
6153
```mermaid
6254
flowchart TD
6355
CBA[Codebase Agent] --> SR[Self-Review]
64-
CBA --> MEM[Memory System]
6556
CBA --> AQE[Autonomous Quality]
66-
6757
AQE --> ITP[Issue-to-PR]
6858
SR --> ITP
69-
7059
ITP --> PAR[PR Auto-Review]
71-
7260
LA[Layered Architecture] -.-> CBA
7361
SEC[Security Patterns] -.-> CBA
7462
TEST[Testing Patterns] -.-> AQE
7563
```
7664

77-
Solid arrows: recommended order. Dashed arrows: optional dependencies.
78-
7965
---
8066

8167
## Quick Reference
8268

83-
!!! note "Section Summary"
84-
One-page cheat sheet of all patterns with key commands and file paths. Printable format.
69+
| File | Location |
70+
|------|----------|
71+
| CBA definition | `.claude/agents/codebase-agent.md` |
72+
| Context files | `.claude/context/*.md` |
73+
| Issue-to-PR | `.github/workflows/issue-to-pr.yml` |
74+
| PR Review | `.github/workflows/pr-review.yml` |
75+
| Dependabot | `.github/workflows/dependabot-auto-merge.yml` |
76+
| Stale | `.github/workflows/stale.yml` |
77+
78+
| Secret | Used By |
79+
|--------|---------|
80+
| `ANTHROPIC_API_KEY` | Issue-to-PR, PR Review |
81+
| `GITHUB_TOKEN` | All workflows (auto-provided) |

0 commit comments

Comments
 (0)