Context Management

AI coding assistants have no memory between sessions. This guide explains how to maintain context effectively.

The Problem

• AI loses context between sessions
• AI forgets what was already built
• AI suggests different patterns each time
• AI doesn't know what NOT to touch

Solution: Live State Files

PROJECT_STATE.md

Purpose: Track current progress at step-level granularity.

Update Frequency: After EVERY step (~30 seconds)

Contents:

• Current phase and step
• Last completed step with timestamp
• Session context and handoff notes
• Completed phases with locked files
• Session log for history
• "NEVER DO" rules

See PROJECT_STATE.md Template for full template.

WHAT_EXISTS.md

Purpose: Inventory of all built components.

Update Frequency: After each phase completion

Contents:

• Database models and tables
• API endpoints by module
• Frontend routes
• Established patterns (copy-from examples)
• Guards and decorators
• Environment variables
• NPM packages

See WHAT_EXISTS.md Template for full template.

Update Procedure

After EVERY Step:

1. Open PROJECT_STATE.md
2. Mark completed step: - [x] Step XX: Description ✅ (HH:MM)
3. Update current step section
4. Update progress: XX of YY steps (ZZ%)
5. Save file

After Phase Completion:

1. Update PROJECT_STATE.md - move phase to Completed
2. Update WHAT_EXISTS.md - add all new components
3. Create git tag: git tag phase-XX-name
4. Commit both files

Additional Context Files

Implementation Plan

Single source of truth for current system state:

• Current building block and status
• Completed and locked building blocks
• Recent decisions and changes
• What AI can modify vs what is locked

See Implementation Plan for current status.

Patterns Documentation

Exact code patterns to follow:

• Service pattern structure
• Controller pattern structure
• Repository pattern structure
• Response format patterns

See Patterns for exact patterns.

Constraints Documentation

Hard rules that must never be violated:

• Version requirements (Prisma 5.x, NOT 6.x)
• Technology restrictions (no GraphQL, no microservices)
• Architecture boundaries
• Complexity limits

See Constraints for hard rules.

Session Workflow

Before Starting Work

1. Read Implementation Plan to understand current state
2. Read current building block specification
3. Read Patterns for code structure
4. Read Constraints for hard rules
5. Check what files are locked (cannot modify)

During Work

1. Follow patterns exactly (no variations)
2. Respect constraints (no exceptions)
3. Don't touch locked files
4. Update context after significant changes

After Completing Work

1. Update Implementation Plan with what was built
2. Document any new patterns in Patterns
3. Update building block status
4. Lock completed files

Context Preservation Strategies

Pattern Locking

Once a pattern is established, lock it:

• Document in Patterns
• Reference in building block
• Reject any AI suggestions to change it

Decision Locking

Once a decision is made, lock it:

• Document in Constraints
• Create ADR if significant
• Reject any AI suggestions to change it

File Locking

Once a building block is complete, lock its files:

• Tag in git
• Document in Implementation Plan
• Reject any AI suggestions to modify

Common Context Loss Scenarios

Scenario 1: AI Forgets Completed Work

Problem: AI suggests rebuilding something already done

Solution:

• Check Implementation Plan for completed blocks
• Reference locked files
• Reject suggestion to rebuild

Scenario 2: AI Suggests Wrong Pattern

Problem: AI suggests different pattern than established

Solution:

• Reference Patterns for correct pattern
• Reject suggestion
• Use established pattern exactly

Scenario 3: AI Wants to Add Technology

Problem: AI suggests adding new technology

Solution:

• Check Constraints for technology restrictions
• Check Boilerplate Definition for locked technologies
• Reject if not approved (requires ADR)

Best Practices

1. Always check context files first - Don't assume AI remembers
2. Reference specific patterns - Point to exact pattern in Patterns
3. Enforce constraints strictly - No exceptions without ADR
4. Update context immediately - After any significant change
5. Lock completed work - Prevent AI from "improving" working code