coding-guidelines（编码指南）

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 for detailed context management strategies
• See references/prompt-patterns.md for prompt structure examples and anti-patterns