Mastering Context Engineering (5): Advanced - Teams and Systems

"Sure, AI needs context, but so do we." — Ken Mugrage, Thoughtworks Principal Technologist

Introduction

So far, we've covered Context Engineering from an individual developer's perspective. Now we scale to teams and organizations.

This article covers:

• How teams share and manage context
• Strategies for handling context in complex systems
• Advanced patterns for "anchoring" AI
• Coordinating multiple AI agents

---

Part 1: Team-Level Context Engineering

1.1 Shared Context Document Management

Single Source of Truth:

project-root/
├── docs/
│   ├── CONTEXT.md           # Project-wide context (team shared)
│   ├── ARCHITECTURE.md      # Architecture details
│   ├── DECISIONS.md         # ADR (Architecture Decision Records)
│   └── CONVENTIONS.md       # Coding conventions
├── .cursorrules             # AI rules (team shared)
└── src/
    └── [modules]/
        └── CONTEXT.md       # Module-specific context

Version Control and Change Tracking:

<!-- CONTEXT.md header -->
# Project Context

**Last Updated:** 2025-12-13
**Maintainers:** @alice, @bob
**Review Cycle:** Monthly

## Change Log
- 2025-12-13: Added search feature architecture (@alice)
- 2025-12-01: Changed auth method JWT → Session (@bob)

1.2 Team Conventions and AI Guidelines

AI Usage Policy:

## AI Usage Policy

### Approved Use Cases
✅ Code generation and refactoring
✅ Test writing
✅ Documentation
✅ Code review assistance
✅ Bug analysis

### Requires Review
⚠️ Security-related code
⚠️ Database schema changes
⚠️ API interface changes

### Prohibited
❌ Direct production deployment
❌ Prompts containing sensitive data
❌ Code with unclear licensing

1.3 Curated Shared Instructions

Team Shared Prompt Library:

## Shared Prompt Library

### Code Review Request

Review the following code.

[Check Items]

• Convention compliance (see CONVENTIONS.md)
• Performance issues
• Security vulnerabilities
• Test coverage

[Code]

{code}

### Architecture Decision

Architecture decision needed.

[Situation]

{situation}

[Options]

{options}

[Constraints]

{constraints}

[Request] Analyze in ADR format.

---

Part 2: Context Management in Complex Systems

2.1 Microservices Environment

Service-Specific Context Separation:

services/
├── user-service/
│   ├── CONTEXT.md          # User service context
├── order-service/
│   ├── CONTEXT.md          # Order service context
└── docs/
    ├── SYSTEM_CONTEXT.md   # Overall system context
    ├── SERVICE_MAP.md      # Inter-service relationships
    └── API_CONTRACTS.md    # API contracts

Documenting Service Relationships:

# SERVICE_MAP.md

## Service Dependencies

┌─────────────┐ ┌─────────────┐ │ Gateway │────▶│ User │ └─────────────┘ └─────────────┘ │ │ ▼ ▼ ┌─────────────┐ ┌─────────────┐ │ Order │────▶│ Payment │ └─────────────┘ └─────────────┘

## Communication Patterns
- Gateway → User: REST (auth)
- Order → Payment: Event (payment request)

2.2 Legacy Codebase

Gradual Context Building:

## Legacy Context Building Strategy

### Phase 1: Discovery (1-2 weeks)
- [ ] Identify major modules
- [ ] Create dependency graph
- [ ] Locate core business logic

### Phase 2: Documentation (2-4 weeks)
- [ ] Write CONTEXT.md for each module
- [ ] Record known issues
- [ ] Make implicit rules explicit

### Phase 3: AI Utilization (ongoing)
- [ ] Accelerate code understanding with AI
- [ ] Establish refactoring plans
- [ ] Gradual improvement

---

Part 3: Advanced Patterns

3.1 Reference Application Pattern

Thoughtworks' "Anchoring coding agents to a reference application":

Concept: Instead of telling AI "do it this way," show "do it like this reference implementation"

Structure:

project/
├── reference/              # Reference implementation
│   ├── feature-complete/   # Complete feature examples
│   │   ├── user-crud/      # CRUD reference
│   │   ├── auth-flow/      # Auth reference
│   │   └── api-endpoint/   # API reference
│   └── README.md           # Reference usage guide
└── src/                    # Actual code

Usage Example:

"I want to create a new API endpoint.

[Reference]
Please refer to reference/feature-complete/api-endpoint/

[Requirements]
- GET /api/products/:id
- Return product details
- Apply caching

[Request]
Implement following the reference implementation patterns."

3.2 Team of Agents Pattern

"Team of coding agents" mentioned in Thoughtworks Technology Radar:

Concept: Instead of giving all context to one AI, separate agents by role

Role Separation:

## Agent Roles

### Architect Agent
- Role: Architecture decisions, design review
- Context: System-wide structure, constraints, ADR
- Output: Design documents, structure proposals

### Developer Agent
- Role: Code implementation
- Context: Module details, conventions, reference code
- Output: Implementation code

### Reviewer Agent
- Role: Code review
- Context: Quality standards, security checklist
- Output: Review comments, improvement suggestions

### Tester Agent
- Role: Test writing
- Context: Test patterns, coverage requirements
- Output: Test code

3.3 Context Hierarchy Pattern

## Context Hierarchy

### Level 0: Global Context
- Company/org standards, security policies
- Applied: All projects

### Level 1: Project Context
- Project overview, architecture, tech stack
- Applied: Entire project

### Level 2: Module Context
- Module responsibilities, internal structure
- Applied: Specific module

### Level 3: Task Context
- Current task details, related files
- Applied: Current task only

---

Part 4: Anti-patterns and Troubleshooting

4.1 Common Mistakes

#	Mistake	Symptom	Solution
1	Context overload	AI misses key points	Select relevant info only
2	Insufficient context	Generic answers	Add specific context
3	Outdated context	Wrong assumptions	Regular updates
4	Contradictory context	Confused output	Consistency review
5	Implicit assumptions	Unexpected results	Write explicitly

4.2 Troubleshooting Guide

When AI ignores context:

1. Is context too long? → Extract essentials
2. Is context in the middle? → Move to start/end
3. Is format consistent? → Restructure
4. Are there contradictions? → Remove

4.3 Context Quality Metrics

## Context Quality Metrics

### Relevance Score
- Ratio of directly relevant information
- Target: > 80%

### Freshness Score
- Ratio of info updated within 30 days
- Target: > 90%

### Consistency Score
- Ratio of non-contradictory info
- Target: 100%

---

Part 5: Future Outlook

5.1 MCP Evolution

Model Context Protocol continues to evolve:

• More data source support
• Real-time context updates
• Context sharing between agents

5.2 Agent-to-Agent (A2A) Protocol

Thoughtworks Technology Radar:

"The agent2agent (A2A) protocol leads the way with standardizing how agents interact with one another."

5.3 Future of Context Engineering

2025: Individual developer skill
  ↓
2026: Team essential capability
  ↓
2027: Organizational standard process
  ↓
Future: Foundation of AI-native development

---

Series Conclusion

What We Learned in 5 Articles

Article 1: Why Vibe Coding and Spec Driven fail Article 2: Context Engineering theory Article 3: Project setup Article 4: Development workflow Article 5: Teams and systems

Core Message

AI is not a tool but a collaborator. Collaborators need context. Context quality determines result quality.

Next Steps

1. Today: Create CONTEXT.md
2. This week: Apply workflow
3. This month: Share with team
4. Ongoing: Improve and evolve

---

References

1. Thoughtworks. (2025, November). "Technology Radar Vol. 33."
2. Mugrage, K. (2025). "From vibe coding to context engineering."
3. Anthropic. "Model Context Protocol Documentation."

---

If this series was helpful, share your Context Engineering journey. Which patterns were most effective?