Understanding Context for AI-Assisted Development

When working with AI agents to generate code, the single most important factor determining quality is context. Unlike human developers who can infer missing information, ask clarifying questions, and notice when specifications are outdated, AI agents require explicit, structured context to generate code that aligns with your business goals, follows your architectural patterns, and integrates correctly with your existing codebase.

This article explains the four types of context every AI agent needs, what each should contain, and how to structure them for maximum effectiveness.

#Quick Reference

AI agents need four types of structured context to generate high-quality, aligned code:

Best practice: Store context in ai-docs/context/ and reference from AGENTS.md or CLAUDE.md so AI agents automatically load it.

#Why Context Matters

The difference between productive AI-assisted development and the “vibe coding trap” is context. Without structured context, AI agents generate code that works in isolation but doesn’t follow your architectural patterns, integrate with your existing codebase, or align with your business priorities.

Without context, a prompt like “Add a shopping cart feature” produces code that works in isolation but uses inconsistent patterns, ignores your technical standards, misses functional requirements and edge cases, and fails to align with business priorities—creating technical debt.

With context—technical strategy, project structure, functional requirements, and business goals—the same prompt generates code that follows established patterns, maintains codebase consistency, handles all specified edge cases, integrates seamlessly, and supports your business objectives. This is what transforms AI from a code generator into a genuine productivity multiplier.

#The Four Context Types

AI agents need four distinct types of context to generate high-quality code. Each answers a different question:

1. Business Context - Why are we building this? What are the business priorities and goals?
2. Functional Context - What should the system do? Who are the users and what are the workflows?
3. Technical Strategy - How should we build it? What are our architectural patterns and standards?
4. Technical Context - Where does code go? How does it integrate with existing systems?

The following sections explain each context type in detail, with complete examples from a real e-commerce project.

%%{init: {"flowchart": {"htmlLabels": false}} }%%
graph LR
    subgraph contexts[" "]
        BC["Business Context

WHY we build"]
        FC["Functional Context

WHAT it should do"]
        TS["Technical Strategy

HOW to build it"]
        TC["Technical Context

WHERE code goes"]
    end

    BC -.->|Business priorities| AI[AI Agent]
    FC -.->|Requirements| AI
    TS -.->|Patterns & standards| AI
    TC -.->|Integration points| AI

    AI -->|Generates| Code["High-Quality
Aligned Code"]

#Business Context

What it answers: Why are we building this? What are the business priorities?

Purpose: Ensures AI agents make decisions that align with business goals and can prioritize correctly when trade-offs arise.

What to include:

• Company overview and market position
• Strategic objectives for the current quarter/year
• Key Performance Indicators (KPIs) and success metrics
• Budget and timeline constraints
• Stakeholder priorities
• Risk assessment
• Trade-off guidelines (e.g., “Security over performance”, “Timeline over features”)

When AI needs this:

• Assisting with architectural decisions
• Helping prioritize features
• Proposing technical solutions aligned with business goals
• Evaluating trade-offs between competing approaches

Which capabilities need this: Typically capabilities at Planning and Requirements phases.

Example - ShopMosy E-commerce Business Context:

# Business Context

## Company Overview
**Company**: ShopMosy - Mid-market B2C e-commerce platform
**Market Position**: Competing in the consumer electronics and
accessories space with established players like Amazon and Best Buy
**Differentiation**: Curated product selection and expert
recommendations for tech enthusiasts

ShopMosy operates in a highly competitive market where conversion
rate and user experience are critical differentiators. The company
has established a loyal customer base but faces challenges with
cart abandonment, particularly on mobile devices.

## Q2 2025 Strategic Objectives

### Primary Goals
1. **Increase Cart Conversion Rate**: 65% → 80%
   - Why: Cart abandonment is our biggest revenue leak
   - Impact: Significant revenue increase without acquiring new
     customers
   - Timeline: 12 weeks

2. **Achieve PCI-DSS Compliance**
   - Status: Non-negotiable regulatory requirement
   - Why: Required for enterprise partnerships and customer trust
   - Timeline: Must complete by end of Q2

### Key Metrics
| Metric           | Current | Target | Why It Matters         |
|------------------|---------|--------|------------------------|
| Cart Conversion  | 65%     | 80%    | Direct revenue impact  |
| Cart Abandonment | 35%     | 20%    | Friction in flow       |
| Checkout Time    | 3.5 min | 2.0min | Speed → conversion     |

## Trade-off Priorities
When making technical decisions, prioritize in this order:
1. **Security and Compliance** (never compromise)
   - Regulatory requirements are non-negotiable
   - Customer trust is foundational to the business
2. **Core Conversion Improvements** (primary strategic goal)
   - Features that directly impact cart conversion take
     precedence
   - UX improvements over new functionality
3. **Performance** (secondary but important)
   - Fast checkout experience supports conversion
   - Mobile performance is critical (60% of traffic)
4. **New Features** (defer if impacts timeline)
   - Nice-to-have features should not delay core objectives

## Constraints
- **Team**: 5 developers (2 senior, 3 mid-level)
- **Timeline**: 12 weeks hard deadline (Q2 2025)
- **Technical Debt**: Must not accumulate - maintain code quality
- **Resources**: Approved budget available for tools/services that
  accelerate delivery

#Functional Context

What it answers: What should the system do? Who uses it and how?

Purpose: Defines functional behavior, business rules, and user interactions so AI agents generate features that match actual requirements.

What to include:

• Actors: Users, roles, personas
• Flows: User journeys, step-by-step processes
• Entities: Data models, relationships
• Integrations: External systems, APIs
• Business Rules: Constraints, validations
• Edge Cases: Error scenarios, boundary conditions
• Metrics: Measures to track feature value and success

When AI needs this:

• Implementing any feature
• Writing test cases
• Handling edge cases
• Validating requirements

Which capabilities need this: Typically all capabilities from Requirements through Maintenance.

Example - Shopping Cart Functional Context:

# Functional Context - Shopping Cart

## Actors
- **Authenticated User**: Registered customer, cart persists 30 days
- **Guest User**: Temporary shopper, cart expires 24 hours
- **Admin**: Internal staff, read-only cart access

## Key Flows

### Add to Cart
1. User clicks "Add to Cart"
2. System validates stock availability
3. System captures unit price (price lock)
4. System adds item or increments quantity
5. System updates cart total

**Edge cases**:
- Out of stock → Show error, don't add
- Cart at capacity (50 items) → Show error
- Low stock (< 5) → Show warning, allow add

## Entities

**Conceptual Data Model**:
- A **User** has one active **Cart**
- A **Cart** contains multiple **CartItems**
- Each **CartItem** references a **Product** and has a quantity
- Each **Product** has a price and availability status

## Business Rules
- Maximum 50 items per cart
- Maximum 99 quantity per item
- Unit price locked at time of add (never updated)
- Cart expires: 30 days (authenticated), 24 hours (guest)
- Guest cart merges with user cart on login (zero data loss)

## Integrations
- **Inventory Service**: Stock validation
- **Pricing Service**: Current price lookups
- **User Service**: Authentication

## Non-Functional Requirements
- **Performance**: All cart operations must complete in < 500ms
- **Reliability**: Stock must be validated before every cart
  modification to prevent overselling

## Metrics
- **Cart Abandonment Rate**: < 35% (user experience quality)
- **Add-to-Cart Conversion**: > 15% (feature adoption)

ai-docs/specs/
├── domain-functional-context.md    # Parent document with overview
├── flows/
│   ├── checkout-flow.md           # Detailed checkout journey
│   ├── cart-management-flow.md    # Cart operations
│   └── user-registration-flow.md  # Registration process

#Technical Strategy

What it answers: How should we build it? What are our architectural principles and standards?

Purpose: Ensures AI agents generate code that follows your architecture, uses your chosen patterns, and maintains consistency across the codebase.

What to include:

• Technology Stack: Languages, frameworks, versions
• Architecture Decision Records (ADRs): Why we chose specific approaches
• Design Patterns: Which patterns to use
• Coding Standards: Naming conventions, style guides
• Testing Requirements: Coverage targets
• Security Standards: Authentication, authorization
• Performance Standards: Response time targets

When AI needs this:

• Writing any code
• Making technical decisions
• Choosing libraries or frameworks
• Structuring new components

Which capabilities need this: Typically all capabilities from Design through Deployment.

Example - Technical Strategy:

# Technical Strategy

## Technology Stack
- **Backend**: Node.js 20.x, TypeScript 5.3+, Express.js,
  PostgreSQL
- **ORM**: TypeORM 0.3.x
- **API Style**: RESTful HTTP/JSON following Zalando API
  Guidelines (see `docs/resources/technical/api-guidelines.md`)

## Development Practices
- **TDD Enforcement**: Write tests before implementation code
  (red-green-refactor cycle)
- **Interface-First Design**: Define interfaces before
  implementations for better contracts and testability
- **Code Review**: All code requires review before merge, minimum
  one approval from senior developer
- **Pair Programming**: Encouraged for complex features and
  knowledge sharing

## Design Patterns & Principles
- **Repository Pattern**: All data access through repositories
  for consistency and testability
- **Action Pattern**: Controllers are thin HTTP handlers, Actions
  contain business logic (Single Responsibility Principle)
- **Dependency Injection**: Constructor injection for all
  dependencies
- **Price Locking**: Unit prices locked at time of add, never
  auto-updated (customer trust, no checkout surprises)

## Coding Standards
- TypeScript strict mode enabled
- camelCase for variables, PascalCase for classes
- All entities extend BaseEntity (id, createdAt, updatedAt)
- ESLint + Prettier for code formatting (see `.eslintrc.js`)
- Maximum function length: 50 lines
- No `any` types - use proper typing or `unknown`

## Testing Strategy
- **Coverage**: Minimum 80% code coverage required
- **Test Pyramid**:
  - Unit tests: ~70% (all business logic)
  - Integration tests: ~20% (repositories, external services)
  - E2E tests: ~10% (critical user flows only)
- **Test-First**: Write tests before implementation
- **Test Naming**: `should_[expected behavior]_when_[condition]`

## API Design Guidelines
Follow Zalando RESTful API Guidelines for all endpoints.
Key principles:
- Resource-oriented URLs (`/carts/{id}` not `/getCart`)
- HTTP verbs match operations (GET, POST, PUT, DELETE)
- Consistent error responses (RFC 7807 Problem Details)
- Versioning via Accept header when needed

Full guidelines: `docs/resources/technical/api-guidelines.md`

## Architecture Decision Records
Key architectural decisions are documented in `docs/adrs/`.
Review relevant ADRs when implementing features that may be
impacted by past decisions.

#Technical Context

What it answers: Where does this code go? What existing code should I reference?

Purpose: Shows AI agents how to integrate new code with your existing codebase by providing project structure, file organization, and reference examples. By defining clear structure and organization patterns, AI agents can find what they need more easily and load only relevant context rather than scanning the entire repository. This becomes particularly valuable in large codebases where loading everything would be inefficient and overwhelming.

What to include:

• Project Structure: Directory layout
• File Naming Conventions: Naming patterns
• Package Descriptions: What each directory contains
• Key Files to Reference: Well-implemented examples
• Integration Points: Where new code connects
• Exclusion Zones: Code AI should NOT scan (e.g., legacy packages)

When AI needs this:

• Adding new files
• Referencing existing code
• Understanding project organization
• Integrating with existing systems

Which capabilities need this: Typically all capabilities from Design through Maintenance.

Example - Technical Context:

# Technical Context

## Project Structure

src/
├── controllers/     # HTTP request handlers (thin layer)
├── actions/        # Business logic (single-purpose)
├── repositories/   # Data access layer
├── domain/
│   ├── entities/   # TypeORM entities
│   └── types/      # TypeScript types
├── middleware/     # Express middleware
├── services/       # External integrations
├── utils/          # Shared utilities
└── legacy/         # ⚠️ DO NOT SCAN OR MODIFY

## Modular Architecture

The system is currently monolithic but organized in independent modules
to enable future evolution into a distributed system. Maintain clear
module boundaries:

- **Keep modules loosely coupled**: Each module (cart, checkout, user)
  should minimize dependencies on other modules
- **Define clear interfaces**: Modules communicate through well-defined
  interfaces, not direct implementation access
- **Avoid cross-module imports**: Don't import directly from another
  module's internal structure
- **Prepare for extraction**: Structure code so modules can be extracted
  into separate services if needed

This modular organization makes the codebase easier to understand,
maintain, and evolve as the system scales.

## File Naming Conventions
- Controllers: `cart-controller.ts`
- Actions: `add-to-cart-action.ts`
- Repositories: `cart-repository.ts`
- Entities: `cart.ts`, `cart-item.ts`

## Key Files to Reference
- `src/repositories/cart-repository.ts` - Repository pattern example
- `src/actions/cart/add-to-cart-action.ts` - Action pattern example
- `src/domain/entities/cart.ts` - Entity structure example

## Important Rules for AI Agents
- New cart feature? → Add to `src/actions/cart/`
- Need data access? → Extend BaseRepository
- **NEVER scan or modify** `src/legacy/` (deprecated v1 API)

#The AGENTS.md Ecosystem

#What is AGENTS.md?

AGENTS.md represents a widely adopted pattern for providing context to AI coding agents. The concept of storing AI agent instructions in a dedicated file at the repository root has become a de facto standard across the industry, though the specific filename and format conventions vary by tool.

Think of it this way:

• README.md is for humans (project introduction, contribution guidelines)
• AGENTS.md is for AI agents (context documents, workflows, patterns)

This pattern is supported by major AI coding tools including OpenAI Codex/Copilot, Google Gemini/Jules, Anthropic Claude Code, Cursor, Factory Droid, Aider, RooCode, and Zed. This widespread adoption means you can write context documents once and use them across different AI tools.

#Other Tool-Specific Context Formats

While the AGENTS.md pattern is universal, different tools also use their own specific formats:

• CLAUDE.md (Claude Code): Claude Code’s context file format
• .cursorrules (Cursor): Cursor’s context file format
• .mdc (Unified Format): A proposed cross-tool format combining YAML frontmatter for metadata with Markdown content for instructions, aiming for compatibility across Claude Code and Cursor

#AGENTS.md as Entry Point

Best practice: Use AGENTS.md as the entry point that references your four detailed context documents. This approach follows widely adopted patterns, works across AI coding tools, keeps AGENTS.md concise, and maintains detailed context in specialized files.

Example AGENTS.md structure:

## Context Documents
When working on this project, reference:
1. ai-docs/context/business-context.md - Business priorities
2. ai-docs/context/functional-context.md - Functional requirements
3. ai-docs/context/technical-strategy.md - Architecture patterns
4. ai-docs/context/technical-context.md - Project structure

## Quick Start
[Workflow instructions...]

#Practical Usage Tips

#1. Start with One Feature

Don’t try to document your entire system at once. Start with one vertical slice—a complete feature from user interface through business logic to data storage.

Iterate incrementally:

• Document one feature thoroughly
• Validate it by building something with AI assistance
• Refine the context based on what worked or didn’t
• Only then move to the next feature

Fill gaps as you discover them: If you realize context for a related feature is missing, add it when needed. AI can help draft context documentation, but humans must provide accurate business priorities, functional requirements, and technical guidelines.

#2. Store Context in Your Repository

Keep context documents in your git repository:

your-project/
├── ai-docs/
│   ├── context/
│   │   ├── business-context.md
│   │   ├── functional-context.md
│   │   ├── technical-strategy.md
│   │   └── technical-context.md
│   ├── specs/
│   │   ├── shopping-cart-spec.md
│   │   ├── checkout-spec.md
│   │   └── payment-spec.md
│   └── adrs/
│       ├── 001-repository-pattern.md
│       ├── 002-action-classes.md
│       └── 003-price-locking.md
├── src/
└── tests/

Benefits:

• Context is versioned with code
• Changes are tracked
• Team members can review updates
• AI agents always have current context

#3. Configure AGENTS.md or CLAUDE.md

If you have AGENTS.md or CLAUDE.md properly configured, AI agents will automatically reference your context documents—you don’t need to list them in every prompt. This saves time and ensures consistency.

With AGENTS.md configured (recommended):

Add a "Save for Later" feature to the shopping cart.

Requirements:
- Available for authenticated users only
- Items saved for later remain for 90 days
- Move items between cart and saved list

The AI agent automatically reads your context from the files specified in AGENTS.md.

Without AGENTS.md (manual reference):

Add a "Save for Later" feature to the shopping cart.

Context:
- See ai-docs/context/business-context.md for priorities
- See ai-docs/specs/cart-spec.md for cart flows
- See ai-docs/context/technical-strategy.md for patterns

Requirements:
[same as above]

Explicit references are still useful when you need to call attention to a specific section or document that’s particularly relevant to the current task.

#4. Keep Context Updated

Context documents are living documentation. Update them when:

• Business priorities change
• New architectural decisions are made
• Project structure evolves
• New patterns emerge
• You discover edge cases

Make context updates part of your pull request checklist.

#5. Use Different Detail Levels for Different Tasks

Not all tasks need all four contexts:

#6. Show, Don’t Just Tell

Include concrete examples alongside your instructions:

Bad (only instruction):

“Use dependency injection”

Good (instruction + example):

“Use dependency injection. Follow this pattern:“

export class AddToCartAction {
  constructor(
    private cartRepository = new CartRepository(),
    private inventoryService = new InventoryService()
  ) {}
}

#7. Document the “Why”, Not Just the “What”

Explain the reasoning behind decisions:

Good:

“We use price locking (capturing unit price at time of add) to prevent user frustration at checkout when prices increase. Users see the same price from add-to-cart through payment.”

Bad:

“Unit prices are stored in the cart_items table”

#Relationship to Spec-Driven Development

Context engineering is the broader concept that includes spec-driven development. Understanding how these work together is key to maximizing AI coding effectiveness.

#Static vs. Dynamic Context

At StrategyRadar.ai, we distinguish between two layers of context:

Static Context (the four context types):

• Business Context, Functional Context, Technical Strategy, Technical Context
• Remains relatively stable across features and tasks
• Defines “how we always work” - the baseline constraints and patterns
• Updated quarterly or when significant architectural decisions change
• Lives in dedicated context documents (e.g., ai-docs/context/business-context.md)

Dynamic Context (specs in spec-driven development):

• Master Spec: Complete snapshot of current system architecture
• Task Specs: Specifications for individual changes within each task
• Evolves continuously as the system grows and changes
• Defines “what the system is now” and “what we’re changing”
• Lives in spec files that update with code changes

#How They Work Together

Both static context and specs provide context to AI. They’re complementary layers:

1. Static context sets the foundation: Business priorities, coding standards, architectural patterns, and project structure remain consistent
2. Dynamic context (specs) builds on top: Master spec captures the current system state, task specs define changes
3. Together they enable precise AI guidance: AI knows both “how we work” (static) and “what we’re building” (dynamic)

Learn more in our guide to Task-Driven and Spec-Driven Development.

#Common Mistakes to Avoid

#1. Vague Business Goals

❌ Bad: “Improve the checkout process”

✅ Good: “Increase cart conversion from 65% to 80% in Q2 2025. Priority: conversion over performance.”

#2. Missing Edge Cases

❌ Bad: “Users can add products to cart”

✅ Good: “Users can add products to cart. Max 50 items. If product out of stock, show error. If low stock (< 5), show warning. Lock unit price at time of add.”

#3. Generic Technical Guidelines

❌ Bad: “Follow best practices”

✅ Good: “All repositories extend BaseRepository. Controllers delegate to Action classes. See src/actions/cart/add-to-cart-action.ts for pattern.”

#4. Outdated Context

❌ Problem: Context documents created once and never updated

✅ Solution: Make updates part of PR process. Add context review to sprint retrospectives.

#5. No Concrete Examples

❌ Bad: “Use the repository pattern”

✅ Good: “Use the repository pattern. See src/repositories/cart-repository.ts for reference implementation.”

#Getting Started

Ready to implement context-driven development? We’ve created a comprehensive AI Coding Checklist that provides a step-by-step framework for setting up context documents, testing with AI, and iterating on your approach.

The checklist covers:

• Creating initial context documents (Business, Functional, Technical Strategy, Technical Context)
• Testing context effectiveness with AI agents
• Expanding coverage and measuring success
• Integrating context updates into your development workflow

Visit the AI Coding Checklist to get started with a proven framework for context-driven development.

#Measuring Success

How do you know if context-driven development is working?

#Qualitative Indicators

✅ AI-generated code requires fewer revisions

✅ New features maintain consistency with existing code

✅ Fewer “this doesn’t match our patterns” PR comments

✅ Faster onboarding for new team members

✅ Less time explaining requirements to AI agents

#Quantitative Metrics

Track these metrics before and after implementing context-driven development:

• PR revision cycles: How many rounds of changes before merge?
• Code review time: How long does review take?
• Pattern violations: How often does code not follow standards?
• Integration issues: How often does new code fail to integrate?
• Time to first working code: How long from prompt to functioning feature?

#Conclusion

Context is the difference between AI agents that generate technical debt and AI agents that genuinely multiply your productivity. The four context types provide a comprehensive framework:

1. Business Strategy and Context - The why and business priorities
2. Domain and Functional Context - The what and functional requirements
3. Technical Strategy and Guidelines - The how and architectural standards
4. Technical Context - The where and integration points

Start small with one feature, create clear context documents, reference them in your prompts, and keep them updated. The investment in creating good context documents pays dividends in code quality, consistency, and development velocity.

The examples throughout this article demonstrate the level of detail needed for effective AI-assisted development. You can copy and adapt these templates to your own projects.

#Frequently Asked Questions

#Related Resources

• Task-Driven and Spec-Driven Development with AI
• The Vibe Coding Trap: Why Unstructured AI Code Generation Fails
• Understanding AI Control Levels in Development