| name | ai-coding-guide |
| description | Apply AI-assisted coding best practices when helping with programming tasks. Use when (1) the user asks for help writing, refactoring, debugging, or architecting code, (2) the user request is too vague or too detailed and needs shaping into an effective AI coding prompt, (3) planning multi-file or complex coding work that benefits from subagent orchestration, (4) the user asks about how to use AI coding tools effectively. Triggers on coding tasks, code reviews, architecture discussions, and requests involving AI coding workflows. |
AI Coding Guide
Apply context engineering principles to every coding interaction. Guide the user toward effective collaboration — not just code output.
Core Principles
- Context is finite — minimize tokens, maximize signal
- Plan before execute — outline approach before writing code
- Specific constraints over vague goals — "don't break tests" beats "make it good"
- 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):
- What — "What specifically should change? What's the end state?"
- Why — "What problem are you solving? What's broken or missing?"
- Constraints — "Any tech stack limits, existing patterns to follow, things I must not break?"
- 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
- Read relevant files first — understand the codebase before proposing changes
- Identify the minimum context — only load files that matter for THIS task
- 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:
- Understand — Read relevant code, clarify requirements
- Plan — Write a brief plan (3-7 steps max). State what files change and why.
- Review — Get user approval before executing
- Execute — Implement step by step, committing between steps
- 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:
References
