Appendix A: Aider Quick Reference¶

This appendix serves as a quick-reference manual for Aider, the Git-native AI assistant used throughout this book. Aider is the primary tool that implements the 3-Tier Strategy from Chapter 2, enabling you to route tasks to the right AI model at the right cost.

1. Installation & Setup¶

1.1 Install Aider¶

# Install via pip (recommended)
pip install aider-chat

# Verify installation
aider --version

# Upgrade to latest version
pip install --upgrade aider-chat

1.2 Environment Configuration¶

Aider reads API keys from your environment. This repository uses a .env file for secure key management:

# Create your .env file (or run make setup)
cp .env.example .env

# Edit .env with your API keys
# DEEPSEEK_API_KEY=sk-...  # Tier 1: Architect
# QWEN_API_KEY=sk-...      # Tier 2: Editor

Never commit .env to version control. The .gitignore file already excludes it.

1.3 Configuration File¶

Create .aider.conf.yml in your repository root (or run make setup):

# .aider.conf.yml - Aider Configuration for aibook
# Following the 3-Tier Strategy from Chapter 2

# Tier 2: Default Editor (80% of tasks)
model: qwen-2.5-coder

# Tier 1: Architect (Complex reasoning tasks)
architect-model: deepseek-chat

# Project Context (Always loaded for AI awareness)
read:
  - AGENTS.md          # The Rules: Behavioral guardrails
  - AI_CONTEXT.md      # The Map: Project facts and definitions
  - README.md          # Human overview
  - mkdocs.yml         # Site structure

# Behavior Controls
auto-commits: false    # Manual commits only (prevents accidental pushes)
confirm: true          # Always confirm before making changes
restrict-read-write: true  # Keep AI focused on documentation, not code

# Cost Optimization
show-model-warnings: true
show-release-notes: false

2. Core Interactive Commands¶

When running aider in your terminal, use these slash commands:

Command	Description	Example
`/add <file>`	Add a file to the chat session (AI can edit it).	`/add docs/03-iac-using-ai.md`
`/drop <file>`	Remove a file from the chat session (saves tokens).	`/drop docs/old-draft.md`
`/read <file>`	Read a file into context without allowing edits (perfect for rules).	`/read AGENTS.md`
`/commit`	Commit all pending changes with AI-generated message.	`/commit`
`/undo`	Undo the last commit and revert file changes.	`/undo`
`/diff`	Show the git diff of the last AI-generated changes.	`/diff`
`/model <name>`	Switch the active model (see 3-Tier Strategy below).	`/model deepseek-chat`
`/run <command>`	Run a shell command and show output.	`/run make validate`
`/exit` or `/quit`	Exit the Aider session.	`/exit`

3. The 3-Tier Strategy in Aider¶

Tier Selection Guide¶

Tier	Model	Use Case	Command	Cost/Task
Tier 1: Architect	`deepseek-chat`	Complex reasoning, structural reviews, architectural planning	`/model deepseek-chat`	~$0.05–$0.15
Tier 2: Editor	`qwen-2.5-coder`	Default: Markdown editing, validation fixes, boilerplate (80% of tasks)	`/model qwen-2.5-coder`	~$0.01–$0.03
Tier 3: Sovereign	`ollama/qwen2.5-coder`	NV1/Government work, sensitive data, offline environments	`/model ollama/qwen2.5-coder`	$0.00

How to Switch Tiers¶

# Start Aider with Tier 2 Editor (default)
aider docs/03-iac-using-ai.md

# Switch to Tier 1 Architect within the session
/model deepseek-chat

# Switch to Tier 3 Sovereign (local, offline)
/model ollama/qwen2.5-coder

# Start directly with a specific model
aider --model deepseek-chat --message "Review this chapter" docs/03-iac-using-ai.md

Using the Architect Model¶

Aider supports a two-model architecture:

# Editor does the writing, Architect provides guidance
aider --model qwen-2.5-coder --architect-model deepseek-chat

This is useful when you want the cost-effective Editor to implement changes while the Architect provides high-level direction.

4. Common Workflows¶

4.1 Improving a Chapter (Tier 2 Editor)¶

# Using the Makefile (recommended)
make improve-chapter CHAPTER=03

# Or manually
aider docs/03-iac-using-ai.md \
  --read AGENTS.md \
  --read AI_CONTEXT.md \
  --message "Improve this chapter for technical accuracy, clarity, and alignment with AGENTS.md patterns. Preserve 3-Tier Strategy and 💰 Cost Check callouts."

4.2 Deep Review (Tier 1 Architect)¶

# Using the Makefile (recommended)
make review-chapter CHAPTER=03

# Or manually (note: no --yes flag, so Aider suggests changes but doesn't apply them)
aider --model deepseek-chat \
  --read AGENTS.md \
  --read AI_CONTEXT.md \
  --message "Perform a deep review of this chapter. Provide specific, actionable suggestions. Do NOT apply changes."

4.3 Sovereign Mode (Tier 3 Local)¶

# Using the Makefile
make sovereign-improve CHAPTER=03

# Or manually
aider --model ollama/qwen2.5-coder \
  --read AGENTS.md \
  --read AI_CONTEXT.md \
  --message "Improve this chapter while ensuring all data stays on this machine."

4.4 Fixing Validation Issues¶

# Using the Makefile
make fix-validation

# Or manually
aider --model qwen-2.5-coder \
  --message "Fix all validation issues reported by 'make validate'. Make minimal, surgical changes." \
  $(find docs -name "*.md" -type f)

5. Cost Optimization Tips¶

5.1 Pre-Flight Cost Check¶

Always estimate token costs before starting a session:

# Using the Makefile
make cost-check CHAPTER=03

# Or manually estimate
python3 scripts/token-estimator.py docs/03-iac-using-ai.md

5.2 Token-Saving Practices¶

Practice	How-To	Savings
Read-only files	Use `/read` for rules files instead of `/add`	10-20%
Targeted editing	Specify exact files, not entire directories	30-50%
Drop completed files	`/drop` files after they're done	20-30%
Use Tier 2 by default	Default to `qwen-2.5-coder` for 80% of tasks	60-80%
Local Tier 3	Use `ollama/qwen2.5-coder` for sensitive work	$0.00

5.3 Session Management¶

# Start a focused session with minimal context
aider docs/03-iac-using-ai.md --read AGENTS.md

# Add files as needed during the session
/add docs/04-app-service-deployment.md
/read AI_CONTEXT.md  # Read but don't edit

# Drop files to save tokens
/drop docs/04-app-service-deployment.md

# Check token usage
/run echo "Current token usage..."

6. Troubleshooting¶

Issue	Cause	Solution
"No API key found"	Missing environment variables	Run `make setup` and add keys to `.env`
Rate limit exceeded	Too many requests to API	Switch to Tier 3 local: `/model ollama/qwen2.5-coder`
Git conflict	Uncommitted changes	`git status` → commit or stash before session
"File not in repo"	File not tracked by Git	`git add <file>` first
Ollama model not found	Model not pulled	`ollama pull qwen2.5-coder`
Aider ignores instructions	Missing guardrails	Ensure `/read AGENTS.md` is in context
Changes too broad	AI rewriting entire sections	Add "Make surgical, targeted improvements" to message

Quick Fixes¶

# Environment issues
make check-env  # Validate environment
make setup      # One-time setup

# Git issues
git status      # Check what's uncommitted
git stash       # Stash changes temporarily

# Model issues
ollama pull qwen2.5-coder  # Pull local model
pip install --upgrade aider-chat  # Update Aider

7. Advanced Configuration¶

7.1 Custom Prompts¶

Create a .aider-prompt.txt file in your repository root:

You are an AI assistant working on the aibook DevOps guide.
ALWAYS follow the rules in AGENTS.md.
ALWAYS refer to AI_CONTEXT.md for project facts.
Use the 3-Tier Strategy to recommend appropriate models.
Prefer surgical, targeted improvements over complete rewrites.

Then use it:

aider --prompt-file .aider-prompt.txt docs/03-iac-using-ai.md

7.2 Aliases for Common Tasks¶

Add to your shell profile (.bashrc, .zshrc):

alias aider-edit='aider --model qwen-2.5-coder --read AGENTS.md --read AI_CONTEXT.md'
alias aider-review='aider --model deepseek-chat --read AGENTS.md --read AI_CONTEXT.md'
alias aider-local='aider --model ollama/qwen2.5-coder --read AGENTS.md --read AI_CONTEXT.md'

7.3 Integration with CI/CD¶

# .github/workflows/ai-validation.yml
name: AI Validation
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Validate with Aider (Tier 2)
        run: |
          pip install aider-chat
          aider --model qwen-2.5-coder \
            --message "Fix validation issues" \
            $(find docs -name "*.md" -type f)

8. Quick Reference Card¶

Essential Commands¶

# Start a session
aider docs/03-iac-using-ai.md

# Add context
/add AGENTS.md          # Editable
/read AI_CONTEXT.md     # Read-only

# Switch models
/model deepseek-chat    # Tier 1
/model qwen-2.5-coder   # Tier 2 (default)
/model ollama/qwen2.5-coder  # Tier 3

# Session control
/commit                 # Commit changes
/undo                   # Undo last change
/diff                   # Show changes
/exit                   # Quit

# Run commands
/run make validate      # Run validation
/run make cost-check CHAPTER=03  # Check costs

Makefile Equivalents¶

Task	Make Command	Aider Equivalent
Improve chapter	`make improve-chapter CHAPTER=03`	See Section 4.1
Review chapter	`make review-chapter CHAPTER=03`	See Section 4.2
Sovereign mode	`make sovereign-improve CHAPTER=03`	See Section 4.3
Fix validation	`make fix-validation`	See Section 4.4
Cost check	`make cost-check CHAPTER=03`	See Section 5.1

9. Next Steps¶

Now that you're comfortable with Aider:

Read Chapter 2 - Understand the 3-Tier Strategy in depth
Try the Makefile workflow - make improve-chapter CHAPTER=03
Experiment with Tier 3 - make sovereign-improve CHAPTER=03 for sensitive work
Customize your config - Edit .aider.conf.yml to match your workflow

🔗 Return to Chapter 2: The Self-Improving Repository