Guidelines and best practices for AI code generation.
1. Context Engineering & Markdown Governance (ContextOps)
The most common mistake teams make is assuming the AI "knows" the codebase because it has access to it. You must explicitly curate the AI's reality.
Centralized Rule Files: Utilize project-root instruction files like .cursorrules, CLAUDE.md, or SKILL.md depending on your IDE/tooling. These files should define your stack choices, architectural patterns, and specific conventions (e.g., "We use Vitest, not Jest. Never write class components. Use single quotes."). Keep these files concise, ideally under 500 lines.
Living Architecture Documents: Maintain an ARCHITECTURE.md file and keep Architecture Decision Records (ADRs). When a developer updates a core library, they must update the corresponding context .md file in the same Pull Request.
Explicit Referencing: Never let the AI guess. Require developers to use precise file targeting (e.g., @src/lib/db.ts) to anchor the AI's logic to concrete examples in your repository.
2. Token Budgeting & Session Architecture
Just because modern LLMs have massive context windows does not mean you should fill them. As context grows, "context rot" occurs, and the AI's ability to respect deep constraints degrades.
Transactional Sessions: Treat AI sessions like database transactions. Define a specific scope, execute the code, commit the working state, and immediately clear the context. Do not engage in marathon, multi-hour chat threads covering multiple features; the AI will eventually lose coherence.
Context Selection (Write Less, Include More): Instead of dumping the entire frontend into the prompt, provide only the exact 50-line configuration, the 200-line user model, and the file signatures needed for the specific task.
Context Compression: If a debugging session gets too long, ask the AI to summarize the learnings, start a new chat session, and paste the summary as the new starting prompt.
3. Multi-Agent Workflows & Planning Modes
Complex tasks should not be generated in a single prompt. Break down the generation process.
Mandatory "Plan Mode": Before writing a single line of execution code, the developer must ask the AI to generate a step-by-step implementation plan (often saved as a PLAN.md file). The engineer reviews, edits, and approves this markdown plan before allowing the AI to build.
Agent Handoffs: Use specialized agents or personas for different stages. Use an architect/planning agent to write the specification, a coding agent to execute, and a distinct terminal/CLI agent to run tests and fix type errors.
Parallel Execution: Leverage Git worktrees to run multiple AI tasks concurrently in separate windows without scrambling your main branch context.
4. Quality Assurance & Test-Driven AI (TDD)
AI generates code rapidly, which means it can generate technical debt rapidly. Force the AI to prove its logic.
AI-Assisted TDD: The workflow should be:
Ask the AI to write the test suite based on expected inputs/outputs (ensure it doesn't mock functionality that doesn't exist yet).
Run the tests and confirm they fail.
Instruct the AI to write the implementation code to make the tests pass.
Combatting Abstraction Failures: AI consistently fails by generating code at the wrong level of abstraction (e.g., putting database logic inside a React UI component). Explicitly tell the AI where the logic belongs in your prompt.
Inverted QA: Instead of just reviewing the AI's code, have the AI probe your understanding. Prompt it with requests like, "Ask me 3 edge-case questions about what happens if this queue fails or receives null values" to uncover scenarios neither of you planned for.
5. Advanced Prompts & Code Quality Directives
Define Anti-Patterns: AI learns exceptionally well from negative examples. In your context files, provide explicit examples of "Do This" alongside "Not That" to prevent it from repeating common architectural mistakes.
Multi-Modal Inputs: Do not limit input to text. For React/Next.js UI components, teach your team to drop screenshots of designs or images of UI bugs directly into the prompt to guide the CSS/Tailwind generation.
Predictable Logging: Require the AI to implement structured logging natively. Instruct it: "Any catch block must use our standard logging format with the transaction ID."