Guides
Writing for AI Agents
Best practices for writing product context that AI coding agents like Claude Code and Cursor can consume effectively.
EpicContext is designed to bridge the gap between human documentation and AI agent consumption. This guide covers how to write context that maximizes value for AI coding assistants.
Why Context Matters for AI
AI coding agents are powerful but lack context about your specific product. Without context, they:
- Make generic technology choices instead of following your stack
- Create inconsistent naming conventions
- Miss business rules and constraints
- Don't understand your users or their needs
Well-structured product context transforms AI agents from generic code generators into team members who understand your product.
Writing Principles
Be Specific, Not Generic
AI agents work best with concrete, specific information.
| Instead of... | Write... |
|---|---|
| "We use modern technologies" | "Frontend: Next.js 15 with App Router, TypeScript strict mode, Tailwind CSS" |
| "Users need an easy experience" | "Primary users are non-technical product managers who need to complete tasks without developer help" |
| "Performance matters" | "Pages must load in under 2 seconds on 3G connections; API responses under 200ms" |
Use Structured Fields
Don't write long prose paragraphs. Use the structured fields each block type provides:
- Personas: Fill in goals, pain points, and behaviors separately
- Features: Specify user stories, acceptance criteria, and priority individually
- Decisions: Document context, options considered, and rationale in distinct fields
Structured fields help AI agents extract exactly the information they need without parsing long documents.
Include Constraints and Non-Goals
AI agents are especially helped by knowing what NOT to do:
- Technical constraints (browser support, accessibility requirements)
- Non-goals (features you've intentionally excluded)
- Architecture decisions with rejected alternatives
Link Related Blocks
Use block relationships to create a connected knowledge graph:
- Link features to the personas they serve
- Link user stories to their parent epics
- Link decisions to the features they affect
These relationships help AI agents understand the full context of any task.
Section-Specific Tips
Brand Content
- Include specific color hex values, not just color names
- List font families with fallbacks
- Provide do's and don'ts for tone of voice with examples
Technical Content
- List exact package versions, not just package names
- Document folder structure conventions
- Include code style preferences (naming conventions, patterns)
User Personas
- Include real quotes from user research when available
- Specify technical proficiency levels
- Document common workflows, not just demographics
The AI-GUIDE.md File
When you export to a CONTEXT folder, EpicContext auto-generates an AI-GUIDE.md file. This serves as the entry point for AI agents and includes:
- Navigation structure for all sections
- Block type schemas and field definitions
- Relationship maps between blocks
- Reading order recommendations
Never edit AI-GUIDE.md manually
The AI-GUIDE.md file is auto-generated from your project data. Manual edits will be overwritten on the next sync.
Measuring Context Quality
Use the project overview dashboard to track:
- Completion percentage — aim for 80%+ across key sections
- Block status distribution — minimize "empty" blocks
- Section coverage — ensure Brand, Product, Users, and Technical are filled in
Next Steps
- Set up the Claude Code integration to test your context
- Review export formats to understand how your content reaches AI agents
Last updated: 2026-02-21