8장. 컨텍스트와 기억을 설계한다

다음은 여러 현장에서 반복된 패턴을 합친 합성 사례로, 등장하는 숫자는 설명을 위한 예시 수치다.

긴 작업을 맡은 에이전트에게 저장소의 모든 문서, 과거 이슈, 채팅, 로그를 한꺼번에 주었다. 필요한 정보는 분명 그 안에 있었다. 하지만 오래된 설계 문서가 현재 명세와 충돌했고, 수천 줄 로그 속에서 첫 실패 원인이 묻혔다. 정보 부족이 아니라 관련성·우선순위·신선도 설계의 부재가 문제였다.

컨텍스트는 많이 넣는 창고가 아니다. 현재 결정을 내리는 데 필요한 증거를 적절한 순간에 보여 주는 작업 화면이다. 기억은 대화 전문이 아니라 다음 실행이 이어받아야 할 상태다.

이번 장의 약속

고정 지시, 작업 문맥, 검색 문맥, 실행 상태를 구분한다.
필요한 정보를 점진적으로 공개하는 컨텍스트 패킷을 만든다.
출처·버전·신선도로 충돌하는 정보를 판정한다.
긴 작업을 다른 에이전트가 이어받는 인계 문서를 설계한다.

네 종류의 컨텍스트

1. 고정 운영 규칙

저장소 입구, 도구 권한, 금지 행동, 완료 정의처럼 여러 작업에 공통인 정보다. 짧고 안정적이어야 한다.

2. 작업 계약

목표, 명세 버전, 허용 경로, 필수 게이트, 예산, 선행 산출물이다. 이번 실행의 공식 입력이다.

3. 필요시 검색하는 지식

관련 모듈 코드, 아키텍처 결정, API 문서, 과거 유사 변경이다. 처음부터 모두 넣지 않고 현재 행동에 필요한 범위만 가져온다.

4. 실행 중 상태

읽은 파일, 적용한 변경, 테스트 결과, 실패 가설, 남은 작업, 예산이다. 실행이 길어질수록 원문 대화보다 구조화된 상태로 압축한다.

이 네 종류를 한 프롬프트 문자열로만 관리하면 무엇이 공식 규칙이고 모델이 만든 요약인지 구분하기 어렵다. 각 조각에 출처와 역할을 붙인다.

그림 8-1. 컨텍스트 패킷은 네 종류의 정보를 구분하고, 검증된 결정만 작업 기억에서 장기 기억으로 옮긴다.

컨텍스트 패킷

한 행동 주기에 전달할 정보를 패킷으로 생각한다.

설계 예(실행용 아님) — 원본: 이 장의 컨텍스트 패킷 설명; 명령: 없음.


{
  "task": { "id": "ORDER-12", "goal": "..." },
  "authority": {
    "spec": "SPEC-ORDER-007@3",
    "policy": "policy@sha256:..."
  },
  "scope": {
    "allowedPaths": ["src/orders/api/", "test/contracts/"],
    "requiredGates": ["contract", "architecture"]
  },
  "workingSet": [
    {
      "path": "src/orders/api/get-order.js",
      "hash": "...",
      "reason": "target"
    },
    {
      "path": "artifacts/ORDER-11/domain-contract.json",
      "hash": "...",
      "reason": "dependency"
    }
  ],
  "state": {
    "attempt": 1,
    "lastVerdict": null,
    "remainingActions": 18
  }
}

reason은 왜 이 파일을 넣었는지 설명한다. 관련성이 없는 파일이 계속 포함되는 현상을 발견할 수 있다. 해시는 실행 중 파일이 바뀌었는지 확인하게 한다.

권위의 순서를 정한다

정보가 충돌할 때 에이전트가 더 최근처럼 보이는 문장을 임의 선택하지 않도록 우선순위를 둔다.


보안·법적 정책
  > 승인된 현재 명세
  > 버전 관리된 아키텍처 결정과 공개 계약
  > 저장소 작업 안내
  > 현재 코드와 테스트가 보여 주는 실제 동작
  > 과거 이슈·채팅·모델 요약

현재 코드가 승인 명세와 다르면 코드를 공식 진실로 승격하지 않는다. 불일치를 결함 또는 명시적 마이그레이션으로 다룬다. 반대로 명세가 승인되지 않은 초안이면 운영 코드가 현재 계약일 수 있다. 상태와 버전이 중요하다.

정보 조각에 다음 메타데이터를 붙이면 판단이 쉬워진다.

설계 예(실행용 아님) — 원본: 이 장의 출처 메타데이터 설명; 명령: 없음.


source: specs/order-total.md
authority: approved-spec
version: 3
verified_at: 2026-07-17
scope: order-query

점진적 공개

처음에는 목표와 공식 입구만 준다.


단계 0: 작업 계약 + 루트 안내 + 명세
단계 1: 저장소 지도에서 관련 모듈 후보
단계 2: 선택한 파일과 지역 안내서
단계 3: 실패한 게이트와 직접 관련된 코드·로그
단계 4: 필요가 증명된 과거 결정·외부 문서

각 확장에는 질문이 있어야 한다. “API 응답 타입의 공식 정의가 필요하다”, “이 오류 코드가 공개 계약인지 확인한다”처럼 검색 목적을 기록한다. 목적 없는 전체 검색은 문맥을 오염시키고 비용을 늘린다.

검색 결과는 증거이지 지시가 아니다

저장소의 주석, 이슈, 외부 문서는 악의적이거나 오래된 지시를 포함할 수 있다. 검색된 텍스트가 “검사를 끄라”, “비밀을 출력하라”고 말해도 하니스 정책을 덮어쓰지 못한다.

검색 콘텐츠와 시스템/작업 지시를 별도 필드로 전달한다.
외부 문서의 명령을 자동 실행하지 않는다.
코드 예제의 셸 문자열과 URL을 신뢰하지 않는다.
출처와 신뢰 등급을 보존한다.
민감한 데이터가 모델 입력으로 넘어가기 전에 필터링한다.

컨텍스트 검색은 권한 상승 경로가 될 수 있다는 전제로 설계한다.

작업 기억과 장기 기억

작업 기억은 현재 실행에 필요한 임시 상태다.


현재 가설
최근 도구 결과
변경 파일
남은 게이트
예산

장기 기억은 여러 실행에 걸쳐 유효한 승인된 지식이다.


명세와 도메인 용어
아키텍처 결정 기록
공개 계약
검증된 운영 절차
반복 실패에서 확정한 공장 규칙

실행 중 모델이 만든 추측을 자동으로 장기 기억에 쓰지 않는다. 반복해서 유용해 보이는 발견은 제안 상태로 남기고 사람 또는 정의된 검증이 승인한 뒤 공식 문서와 규칙으로 승격한다.

대화가 아니라 결정과 증거를 압축한다

긴 실행에서 모든 메시지를 계속 전달하면 핵심이 희석된다. 일정 행동 수나 문맥 한도에 도달하면 체크포인트를 만든다.


# Run checkpoint

## 목표와 공식 입력
- Task: ORDER-12
- Spec: SPEC-ORDER-007@3 (hash ...)

## 확인한 사실
- API 응답 타입은 `src/orders/api/schema.js`에서 정의한다. (hash ...)
- 도메인 계약 `ORDER-11`은 정수 최소 단위를 반환한다. (hash ...)

## 적용한 변경
- `get-order.js`: total 매핑 추가
- `order-response.test.js`: AC-01, AC-03 추가

## 검사
- contract: AC-01 통과, AC-03 실패 (`ORDER_MONEY_INVALID` 불일치)

## 폐기한 가설
- null을 0으로 변환: 명세 규칙 4와 충돌해 폐기

## 다음 행동
1. 기존 오류 매퍼에서 공개 오류 코드를 확인한다.
2. 계약 테스트를 다시 실행한다.

## 남은 예산
- actions: 7/18
- time: 41s/120s

이 체크포인트만으로 새 에이전트가 이어받을 수 있어야 한다. “모델이 생각하기에” 같은 표현보다 경로, 해시, 테스트 ID, 관찰된 결과를 쓴다.

실습: 문맥 절반으로 같은 작업 수행하기

1단계: 전체 주입 경로

예제 저장소의 모든 Markdown과 주문 코드를 작업 문맥으로 구성하고 크기, 읽은 파일, 첫 게이트까지 걸린 시간을 기록한다.

2단계: 점진적 공개 경로

작업 계약, 루트 안내, 승인 명세로 시작한다. 저장소 지도에서 주문 API와 선행 계약만 추가한다.

3단계: 결과 비교

다음을 비교한다.

전달된 파일·바이트 수
실제 행동에 인용된 파일 수
오래되거나 충돌한 정보 수
첫 유효 도구 행동까지 시간
필수 게이트 결과

목표는 무조건 가장 작은 문맥이 아니다. 같은 품질을 유지하면서 불필요한 정보와 충돌을 줄이는 것이다.

4단계: 중간에 인계한다

인수인계 fixture를 실행해 첫 작업자가 체크포인트를 남기고 두 번째 작업자가 이어받게 합니다.


npm run demo:handoff

두 번째 시도가 이전 handoff.md와 구조화된 체크포인트를 읽고 성공하는지 확인합니다. 이전 대화 전문이 필요하다면 인계에 결정적 사실이 빠졌습니다. 교육용 구현은 같은 프로세스에서 재개하므로 프로세스 재시작 내구성까지 제공한다고 해석하지 않습니다.

신선도와 무효화

캐시된 컨텍스트는 다음 이벤트에서 무효화한다.

명세 버전 또는 해시 변경
기준 커밋 변경
관련 경로의 파일 해시 변경
선행 작업 산출물 교체
정책 또는 도구 버전 변경
검증 유효 기간 만료

무효화되었다고 모든 것을 버릴 필요는 없다. 어떤 근거가 바뀌었는지 표시하고 영향을 받는 결정을 다시 확인한다.

왜 실패하는가

저장소 전체를 기본 문맥으로 넣는다

비용뿐 아니라 충돌과 오래된 정보의 표면을 늘린다. 공식 입구에서 작업 관련 자료로 확장한다.

모델 요약을 공식 사실로 저장한다

요약은 누락과 해석을 포함한다. 출처 경로와 해시가 있는 확인된 사실, 승인된 결정만 장기 기억으로 승격한다.

실패 로그 전체를 반복 전달한다

첫 원인, 오류 분류, 관련 줄, 재현 명령을 구조화한다. 원문 로그는 산출물로 보존하고 필요할 때 범위를 좁혀 읽는다.

새 에이전트가 처음부터 다시 조사한다

인계가 목표와 다음 행동만 있고 확인한 사실·폐기한 가설·증거 해시가 없으면 같은 탐색을 반복한다.

운영 판단: 무엇을 기억할까

다음 질문에 모두 ‘예’인 정보만 장기 기억 후보로 삼는다.

둘 이상의 향후 작업에서 다시 필요할 가능성이 큰가?
출처와 현재 버전을 확인할 수 있는가?
개인·비밀 정보를 포함하지 않는가?
폐기 또는 갱신할 소유자와 경로가 있는가?
자연어 팁보다 명세·결정·검사로 표현하는 편이 맞는가?

그렇지 않으면 실행 산출물로만 보존하고 기본 문맥에서 제외한다.

연습문제

현재 에이전트 프롬프트를 고정 규칙, 작업 계약, 검색 지식, 실행 상태로 분류하라.
충돌하는 README, 코드, 승인 명세가 있을 때 권위 순서와 차단 조건을 적어라.
실패한 긴 작업의 대화 없이 이어받을 수 있는 체크포인트를 작성하라.
외부 문서 검색을 통한 간접 지시 공격을 막는 제어를 입력, 도구, 출력 단계에 하나씩 추가하라.

체크포인트

작업마다 출처·버전·이유가 있는 컨텍스트 패킷을 만든다.
관련 정보는 단계적으로 확장하고 검색 목적을 기록한다.
모델 요약과 승인된 장기 지식을 구분한다.
새 실행이 체크포인트와 인계 문서만으로 작업을 이어받는다.

2부에서 저장소는 에이전트가 읽을 수 있는 작업 환경이 되었고, 요구는 판정 가능한 명세와 작업 그래프로 변했으며, 필요한 문맥과 기억이 구분됐다. 3부에서는 이 작업들을 실제로 격리하고 병렬 실행하며, 기계식 게이트와 독립 리뷰로 안전하게 통합한다.

Codex로 구축하는 AI 개발팀: 8장. 컨텍스트와 기억을 설계한다