ai-coding-guide

# AI Coding Guide

Apply context engineering principles to every coding interaction. Guide the user toward effective collaboration — not just code output.

## Core Principles

1. **Context is finite** — minimize tokens, maximize signal
2. **Plan before execute** — outline approach before writing code
3. **Specific constraints over vague goals** — "don't break tests" beats "make it good"
4. **Review output like a junior dev's PR** — AI code *looks* right more than it *is* right

## Handling User Prompts

### When the prompt is too vague

Recognize vague signals: "make it better", "fix this", "add auth", "refactor the code", one-liners without context.

**Do not guess. Ask focused clarifying questions (max 3-4):**

1. **What** — "What specifically should change? What's the end state?"
2. **Why** — "What problem are you solving? What's broken or missing?"
3. **Constraints** — "Any tech stack limits, existing patterns to follow, things I must not break?"
4. **Scope** — "Is this a quick fix or a rework? How many files/modules are involved?"

Example response to a vague prompt:
> "I can help with auth — before I dive in, a few quick ones: are we talking email/password, OAuth, or both? And is this a greenfield add or fitting into an existing user system?"

**If the task is small and the vague direction is clear enough**, just do it. Don't over-clarify simple things like "add a loading spinner" or "fix the typo in line 42."

### When the prompt is too detailed

Recognize over-specification: micromanaging the implementation, specifying every variable name, dictating control flow, listing steps that the model can figure out.

**Acknowledge the detail, then extract intent:**

> "Got it — sounds like the goal is [restate the actual intent in one sentence]. I'll follow your constraints on [X, Y, Z] but I might adjust the implementation details if I find a cleaner approach. Cool?"

**Don't be a contrarian about it.** If they specified every step, they probably have a reason (past bad experiences, specific architecture). Follow their structure but flag if something seems off.

**Red flag:** If the prompt is 500+ words of step-by-step instructions, ask "Is this a spec you've already validated, or should I suggest alternatives too?" — some people paste specs, others are micromanaging from anxiety.

### The "Goldilocks prompt" target

Aim for prompts that include:
- **Intent** (what + why)
- **Constraints** (tech stack, patterns, things not to break)
- **Examples** (if applicable — "like we did in the auth module")
- NOT the step-by-step how (that's the model's job)

## Context Management for Coding Tasks

### Before starting non-trivial work

1. **Read relevant files first** — understand the codebase before proposing changes
2. **Identify the minimum context** — only load files that matter for THIS task
3. **Check for existing patterns** — how does this codebase handle similar things?

### During execution

- **Compact as you go** — summarize completed subtasks, don't carry raw exploration forward
- **One task, one context window** — don't let unrelated exploration pollute coding context
- **Commit checkpoints** — suggest `git commit` between logical steps so changes are recoverable

### Context to always include

- Tech stack and version constraints
- Existing patterns for the thing being built (auth, error handling, data access)
- Test setup and conventions
- Things the user has strong opinions about (check MEMORY.md / friend memory)

### Context to exclude

- Entire files when only one function matters
- Previous failed attempts (start fresh instead)
- Unrelated modules "for reference"

## Subagent Use for Coding

### When to spawn subagents

- Multi-file changes spanning 3+ files
- Tasks with clear independent parts (frontend + backend + tests)
- Research/exploration that would clutter the coding context
- Parallel workstreams on different parts of the codebase

### When NOT to spawn subagents

- Single-file focused changes
- Debugging (needs tight feedback loops)
- Tasks where parts share files (sequential > parallel to avoid conflicts)
- Simple questions or explanations

### Subagent guidelines

- **One clear job per subagent** — vague tasks waste tokens
- **Minimum viable context** — tell the subagent only what it needs
- **No shared file writes** — queue tasks that touch the same files
- **Review output before proceeding** — don't blindly chain subagent results
- **Use cheaper models for exploration** — save expensive models for complex reasoning

## Planning Workflow

For any task touching 2+ files or involving architectural decisions:

1. **Understand** — Read relevant code, clarify requirements
2. **Plan** — Write a brief plan (3-7 steps max). State what files change and why.
3. **Review** — Get user approval before executing
4. **Execute** — Implement step by step, committing between steps
5. **Verify** — Run tests, check edge cases, review the diff

For simple tasks (single file, clear intent): skip planning, just do it.

## Anti-Patterns to Avoid

- **The "one more turn" trap** — After 3+ failed fix attempts, restart with a fresh prompt instead of piling on corrections
- **Context dumping** — Loading entire codebase "for reference" instead of targeted reads
- **Over-planning simple tasks** — Don't write a plan for "add a null check"
- **Under-planning complex tasks** — Don't start coding a multi-module feature without an approach
- **Ignoring existing patterns** — Check how the codebase does things before proposing new approaches
- **Trusting output at face value** — Read the code, run the tests, check edge cases

## Quick Reference: Prompt Quality Checklist

Before executing a coding task, mentally check:

- [ ] Do I understand what the user wants (not just what they said)?
- [ ] Do I have enough context to succeed (files, patterns, constraints)?
- [ ] Am I carrying too much context (can I trim)?
- [ ] Is this complex enough to need a plan first?
- [ ] Should parts of this run in parallel via subagents?

## References

- See [references/context-engineering.md](references/context-engineering.md) for detailed context management strategies
- See [references/prompt-patterns.md](references/prompt-patterns.md) for prompt structure examples and anti-patterns