Context Engineering 완전 정복 (5): 고급 - 팀과 시스템

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

들어가며

지금까지 개인 개발자 관점에서 Context Engineering을 다뤘습니다. 이제 팀과 조직으로 확장합니다.

이 글에서는:

팀이 맥락을 공유하고 관리하는 방법
복잡한 시스템에서 맥락을 다루는 전략
AI를 "앵커링"하는 고급 패턴
여러 AI 에이전트를 조율하는 방법

Part 1: 팀 레벨 Context Engineering

1.1 공유 맥락 문서 관리

단일 소스 of Truth:

project-root/
├── docs/
│   ├── CONTEXT.md           # 프로젝트 전체 맥락 (팀 공유)
│   ├── ARCHITECTURE.md      # 아키텍처 상세
│   ├── DECISIONS.md         # ADR (Architecture Decision Records)
│   └── CONVENTIONS.md       # 코딩 컨벤션
├── .cursorrules             # AI 규칙 (팀 공유)
└── src/
    └── [modules]/
        └── CONTEXT.md       # 모듈별 맥락

버전 관리와 변경 추적:

<!-- CONTEXT.md 헤더 -->
# Project Context

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

## Change Log
- 2025-12-13: 검색 기능 아키텍처 추가 (@alice)
- 2025-12-01: 인증 방식 변경 JWT → Session (@bob)

팀원 기여 가이드라인:

## Contributing to Context Documents

### When to Update
- 새로운 아키텍처 결정 시
- 주요 기술 스택 변경 시
- 중요한 교훈을 얻었을 때
- 컨벤션 변경 시

### How to Update
1. 브랜치 생성: `docs/update-context-[topic]`
2. 변경 사항 작성
3. PR 생성, 최소 1명 리뷰
4. Change Log 업데이트

### Review Checklist
- [ ] 기존 내용과 모순 없음
- [ ] 구체적 예시 포함
- [ ] 최신 상태 반영

1.2 팀 컨벤션과 AI 가이드라인

AI 사용 정책:

## AI Usage Policy

### Approved Use Cases
✅ 코드 생성 및 리팩토링
✅ 테스트 작성
✅ 문서화
✅ 코드 리뷰 보조
✅ 버그 분석

### Requires Review
⚠️ 보안 관련 코드
⚠️ 데이터베이스 스키마 변경
⚠️ API 인터페이스 변경
⚠️ 인프라 설정

### Prohibited
❌ 프로덕션 직접 배포
❌ 민감 데이터 포함 프롬프트
❌ 라이선스 불명확한 코드 사용

리뷰 프로세스:

## AI-Generated Code Review Process

1. **생성 단계**
   - CONTEXT.md 참조 확인
   - .cursorrules 적용 확인

2. **자체 검토**
   - 코드 이해 여부 확인
   - 테스트 실행
   - 보안 체크리스트

3. **팀 리뷰**
   - AI 생성 코드 명시
   - 변경 의도 설명
   - 일반 PR과 동일 기준 적용

1.3 Curated Shared Instructions

Thoughtworks가 제안하는 팀 공유 프롬프트 라이브러리:

## Shared Prompt Library

### 코드 리뷰 요청

다음 코드를 리뷰해줘.

[체크 항목]

우리 컨벤션 준수 (CONVENTIONS.md 참조)
성능 이슈
보안 취약점
테스트 커버리지

[코드]

{code}


### 버그 분석

버그를 분석해줘.

[증상]

{symptoms}

[재현 단계]

{steps}

[관련 코드]

{code}

[요청]

가능한 원인 나열
각 원인의 가능성 평가
디버깅 전략 제안


### 아키텍처 결정

아키텍처 결정이 필요해.

[상황]

{situation}

[옵션]

{options}

[제약]

{constraints}

[요청] ADR 형식으로 분석해줘.

맥락
결정
결과
대안

1.4 지속적 개선 프로세스

## Context Document Improvement Cycle

### Weekly
- [ ] 새로운 결정 사항 DECISIONS.md에 추가
- [ ] 발견된 교훈 기록

### Monthly
- [ ] CONTEXT.md 전체 리뷰
- [ ] 오래된 정보 업데이트/제거
- [ ] 팀 피드백 수집

### Quarterly
- [ ] AI 사용 패턴 분석
- [ ] 효과적인 프롬프트 라이브러리 업데이트
- [ ] 새로운 도구/패턴 평가

Part 2: 복잡한 시스템에서의 맥락 관리

2.1 마이크로서비스 환경

서비스별 맥락 분리:

services/
├── user-service/
│   ├── CONTEXT.md          # 사용자 서비스 맥락
│   └── ...
├── order-service/
│   ├── CONTEXT.md          # 주문 서비스 맥락
│   └── ...
├── payment-service/
│   ├── CONTEXT.md          # 결제 서비스 맥락
│   └── ...
└── docs/
    ├── SYSTEM_CONTEXT.md   # 전체 시스템 맥락
    ├── SERVICE_MAP.md      # 서비스 간 관계
    └── API_CONTRACTS.md    # API 계약

서비스 간 관계 문서화:

# SERVICE_MAP.md

## Service Dependencies

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


## Communication Patterns
- Gateway → User: REST (인증)
- Gateway → Order: REST (주문 생성)
- Order → Payment: Event (결제 요청)
- Payment → Order: Event (결제 완료)

## Shared Contracts
- 모든 서비스: 공통 에러 형식
- 이벤트: CloudEvents 스펙 준수

크로스 서비스 작업 시 맥락:

"Order 서비스에서 Payment 서비스를 호출하는 로직을 수정하려고 해.

[시스템 맥락]
- 마이크로서비스 아키텍처
- 이벤트 기반 통신 (Kafka)
- 최종 일관성 모델

[관련 서비스]
- Order: 주문 생성, 상태 관리
- Payment: 결제 처리, 환불

[현재 이슈]
결제 실패 시 주문 상태 롤백이 안 됨

[제약]
- 분산 트랜잭션 사용 안 함
- Saga 패턴 적용 중"

2.2 레거시 코드베이스

점진적 맥락 구축:

## Legacy Context Building Strategy

### Phase 1: 발견 (1-2주)
- [ ] 주요 모듈 식별
- [ ] 의존성 그래프 작성
- [ ] 핵심 비즈니스 로직 위치 파악

### Phase 2: 문서화 (2-4주)
- [ ] 각 모듈 CONTEXT.md 작성
- [ ] 알려진 이슈 기록
- [ ] 암묵적 규칙 명시화

### Phase 3: AI 활용 (지속)
- [ ] AI로 코드 이해 가속화
- [ ] 리팩토링 계획 수립
- [ ] 점진적 개선

AI를 활용한 레거시 이해:

"이 레거시 코드를 분석해줘.

[파일]
{`{legacy_code}`}

[요청]
1. 이 코드가 하는 일 요약
2. 주요 의존성 식별
3. 잠재적 문제점
4. 리팩토링 제안

[주의]
- 이 코드는 10년 전 작성됨
- 원작자 부재
- 테스트 없음"

2.3 멀티 레포지토리

레포 간 맥락 연결:

# CROSS_REPO_CONTEXT.md

## Repository Map

| Repo | Purpose | Dependencies |
|------|---------|--------------|
| frontend | React SPA | api-client |
| backend | Express API | shared-types |
| shared-types | TypeScript 타입 | - |
| api-client | API 클라이언트 | shared-types |
| infra | Terraform | - |

## Shared Conventions
- 모든 레포: ESLint 공통 설정
- 타입: shared-types에서 관리
- 버전: Semantic Versioning

## Cross-Repo Changes
타입 변경 시:
1. shared-types 먼저 업데이트
2. api-client 업데이트
3. frontend/backend 동시 업데이트

Part 3: 고급 패턴

3.1 Reference Application 패턴

Thoughtworks가 제안하는 "Anchoring coding agents to a reference application":

개념: AI에게 "이렇게 해야 해"라고 말하는 대신, "이 참조 구현처럼 해"라고 보여주기

구조:

project/
├── reference/              # 참조 구현
│   ├── feature-complete/   # 완성된 기능 예시
│   │   ├── user-crud/      # CRUD 참조
│   │   ├── auth-flow/      # 인증 참조
│   │   └── api-endpoint/   # API 참조
│   └── README.md           # 참조 사용 가이드
└── src/                    # 실제 코드

참조 앱 선택 기준:

## Reference Application Criteria

### Must Have
- 팀 컨벤션 100% 준수
- 테스트 커버리지 높음
- 문서화 완벽
- 최신 패턴 적용

### Should Have
- 다양한 케이스 커버
- 에러 핸들링 예시
- 성능 최적화 예시

### Nice to Have
- 엣지 케이스 처리
- 접근성 고려
- 국제화 예시

활용 예시:

"새로운 API 엔드포인트를 만들려고 해.

[참조]
reference/feature-complete/api-endpoint/ 를 참고해줘.

[요구사항]
- GET /api/products/:id
- 제품 상세 정보 반환
- 캐싱 적용

[요청]
참조 구현의 패턴을 따라서 구현해줘."

3.2 Team of Agents 패턴

Thoughtworks Technology Radar에서 언급된 "Team of coding agents":

개념: 하나의 AI에게 모든 맥락을 주는 대신, 역할별로 에이전트를 분리

역할 분리:

## Agent Roles

### Architect Agent
- 역할: 아키텍처 결정, 설계 리뷰
- 맥락: 시스템 전체 구조, 제약 조건, ADR
- 출력: 설계 문서, 구조 제안

### Developer Agent
- 역할: 코드 구현
- 맥락: 모듈별 상세, 컨벤션, 참조 코드
- 출력: 구현 코드

### Reviewer Agent
- 역할: 코드 리뷰
- 맥락: 품질 기준, 보안 체크리스트
- 출력: 리뷰 코멘트, 개선 제안

### Tester Agent
- 역할: 테스트 작성
- 맥락: 테스트 패턴, 커버리지 요구사항
- 출력: 테스트 코드

오케스트레이션:

1. 요구사항 → Architect Agent
   "이 기능을 어떻게 설계할까?"
   
2. 설계 → Developer Agent
   "이 설계대로 구현해줘"
   
3. 구현 → Reviewer Agent
   "이 코드를 리뷰해줘"
   
4. 리뷰 피드백 → Developer Agent
   "피드백 반영해서 수정해줘"
   
5. 최종 코드 → Tester Agent
   "테스트 작성해줘"

3.3 맥락 계층화 패턴

## Context Hierarchy

### Level 0: Global Context
- 회사/조직 표준
- 보안 정책
- 공통 컨벤션
- 적용: 모든 프로젝트

### Level 1: Project Context
- 프로젝트 개요
- 아키텍처
- 기술 스택
- 적용: 프로젝트 전체

### Level 2: Module Context
- 모듈 책임
- 내부 구조
- 의존성
- 적용: 특정 모듈

### Level 3: Task Context
- 현재 작업 상세
- 관련 파일
- 즉각적 제약
- 적용: 현재 작업만

계층 간 상속:

Global → Project → Module → Task
  │         │         │        │
  └─────────┴─────────┴────────┘
         맥락 상속 및 오버라이드

Part 4: 안티패턴과 트러블슈팅

4.1 흔한 실수 15가지

#	실수	증상	해결책
1	맥락 과부하	AI가 핵심을 놓침	관련 정보만 선별
2	맥락 부족	일반적인 답변만	구체적 맥락 추가
3	오래된 맥락	잘못된 가정	정기 업데이트
4	모순된 맥락	혼란스러운 출력	일관성 검토
5	암묵적 가정	예상과 다른 결과	명시적으로 작성
6	맥락 리셋	매번 처음부터	세션 요약 전달
7	도구 취급	협업 실패	대화형 접근
8	리뷰 스킵	품질 저하	필수 리뷰 프로세스
9	피드백 미축적	같은 실수 반복	피드백 기록
10	일관성 없는 형식	파싱 어려움	템플릿 사용
11	과도한 추상화	구체성 부족	실제 예시 포함
12	구체성 부족	모호한 출력	상세 요구사항
13	맥락 사일로	팀 불일치	공유 문서
14	버전 불일치	충돌	버전 관리
15	품질 무시	기술 부채	품질 지표

4.2 트러블슈팅 가이드

AI가 맥락을 무시할 때:

1. 맥락이 너무 긴가? → 핵심만 추출
2. 맥락이 중간에 있나? → 시작/끝으로 이동
3. 형식이 일관적인가? → 구조화
4. 모순이 있나? → 제거

일관성 없는 출력:

1. 참조 코드 제공했나? → Reference Application 사용
2. 예시가 충분한가? → Few-shot 추가
3. 컨벤션이 명확한가? → 구체적 규칙 명시

4.3 맥락 품질 측정

## Context Quality Metrics

### Relevance Score (관련성)
- 현재 작업에 직접 관련된 정보 비율
- 목표: > 80%

### Freshness Score (최신성)
- 30일 이내 업데이트된 정보 비율
- 목표: > 90%

### Consistency Score (일관성)
- 모순 없는 정보 비율
- 목표: 100%

### Completeness Score (완전성)
- 필수 섹션 작성 비율
- 목표: 100%

Part 5: 미래 전망

5.1 MCP의 발전

Model Context Protocol은 계속 진화 중:

더 많은 데이터 소스 지원
실시간 맥락 업데이트
에이전트 간 맥락 공유

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 Context Engineering의 미래

2025: 개인 개발자의 기술
  ↓
2026: 팀 필수 역량
  ↓
2027: 조직 표준 프로세스
  ↓
미래: AI 네이티브 개발의 기본

시리즈 결론

5개 글에서 배운 것

Article 1: 왜 Vibe Coding과 Spec Driven이 실패하는가

맥락 제거의 문제
$4B 기술 부채 위기
업계의 방향 전환

Article 2: Context Engineering의 이론

정의와 핵심 개념
Context Window 이해
맥락의 5가지 구성 요소

Article 3: 프로젝트 셋업

CONTEXT.md 작성
Cursor 설정
MCP 활용

Article 4: 개발 워크플로우

맥락 우선 대화 패턴
4단계 워크플로우
맥락 연속성

Article 5: 팀과 시스템

팀 레벨 관리
복잡한 시스템 전략
고급 패턴

핵심 메시지

AI는 도구가 아니라 협업자입니다. 협업자에게는 맥락이 필요합니다. 맥락의 품질이 결과의 품질을 결정합니다.

다음 단계

오늘: CONTEXT.md 만들기
이번 주: 워크플로우 적용
이번 달: 팀과 공유
지속: 개선하고 발전시키기

References

Thoughtworks. (2025, November). "Technology Radar Vol. 33."
Mugrage, K. (2025). "From vibe coding to context engineering."
Anthropic. "Model Context Protocol Documentation."
Google. "Agent-to-Agent Protocol Specification."

이 시리즈가 도움이 되셨다면, 여러분의 Context Engineering 여정을 공유해주세요. 어떤 패턴이 가장 효과적이었나요?