The six types of context your AI needs (and how to document them)

Introduction

A developer asked AI to add rate limiting and wasted 5 hours because the AI lacked knowledge about the system’s multi-tenant architecture, Redis usage, and user tier differentiation. After analyzing hundreds of similar cases, I identified six categories of missing context that explain nearly every AI-generated code failure.

1. Architectural context: the big picture

What AI needs to know: overall system architecture, service communication methods, data flow patterns, deployment architecture, multi-tenancy models.

Without architectural context, AI might make direct database calls when a service exists, ignore tenant isolation in multi-tenant systems, create synchronous calls in event-driven architectures, or miss caching layers.

Real impact: Without context, AI suggested direct database queries. With context, it generated proper service client calls with tenant isolation and caching, saving 3 hours of review and refactoring.

2. Pattern context: your team’s conventions

What AI needs to know: naming conventions, file organization patterns, error handling approaches, testing patterns, code structure preferences.

AI generates generic patterns that do not match your codebase, resulting in misplaced files, inconsistent naming, skipped validations, missed logging, or incorrect error handling.

Real impact: A developer asked AI to create a registration endpoint. Without pattern context, AI generated 150 lines with wrong file directories, manual error handling, and custom response formats, requiring 4 hours of restructuring. With context, the generated code matched conventions perfectly and passed review in 30 minutes.

3. Constraint context: the non-obvious rules

What AI needs to know: performance requirements, rate limits and quotas, database query patterns, memory limitations, compliance requirements, business rules.

These constraints are not obvious from looking at code but will cause production issues if violated.

Real impact: A developer asked AI to create a user export feature. Without constraints, the code loaded all 500,000 users into memory and crashed in production. With constraints, AI generated stream-based processing with batch handling and PII protection, working immediately.

4. Historical context: why code exists this way

What AI needs to know: past incidents and root causes, why certain patterns were chosen, what approaches failed before, technical debt explanations, deprecated patterns to avoid.

That “unnecessarily complex” code often has a story. Without knowing the history, AI will confidently simplify away hard-earned lessons.

Examples:

• 2023-Q2: Authentication bypass via cache poisoning led to the rule of never using in-memory caching for auth
• 2023-Q3: Database connection pool exhaustion led to the rule of never executing queries in loops

5. Integration context: what this touches

What AI needs to know: internal service dependencies, external API integrations, database relationships, event publishers/subscribers, webhook handlers.

Modern systems are interconnected. Changes ripple across dependencies, and AI must understand what it is affecting.

Real impact: A developer asked AI to implement “delete user” without integration context. AI generated a simple delete statement, missing OAuth cleanup, session invalidation, event publication, audit logging, and cascading deletes. With context, the generated code handled all dependencies correctly within a transaction.

6. Security context: lessons from vulnerabilities

What AI needs to know: past security incidents, authentication/authorization patterns, data encryption requirements, input validation rules, common vulnerabilities to avoid.

Security relies on learning from specific vulnerabilities, not just following generic best practices.

Real impact: Without security context, AI generated an endpoint with no authentication, authorization, tenant isolation, input validation, rate limiting, or audit logging. With context, AI generated a fully secure endpoint with all required protections that passed review immediately.

Putting it all together

The complete structure for copilot-instructions.md:

1. Architecture Overview: System design, multi-tenancy model, deployment setup
2. Code Patterns and Conventions: File organization, naming, error handling, testing
3. Critical Constraints: Performance requirements, rate limits, compliance rules
4. Historical Context: Past incidents, why patterns exist, deprecated approaches
5. Integration Points: Internal services, external APIs, event bus, database relationships
6. Security Requirements: Auth patterns, encryption, validation, past vulnerabilities
7. Reference Implementations: Links to example code for patterns
8. Common Mistakes to Avoid: Specific issues that have caused problems

Implementation plan

Week 1: Identify the biggest gap by reviewing recent AI-generated code issues.

Week 2: Document one context type thoroughly with 2-3 examples (3-4 hours).

Week 3: Test and refine based on developer feedback (1-2 hours).

Week 4: Add the next context type (2-3 hours).

By the end of month one, you will have comprehensive context documentation. The compound returns start immediately.