AI 코딩 에이전트에게도 ‘프로젝트 기억’이 필요하다

AGENTS.md, Agent, Skill, Memory를 연결해 스스로 경험을 축적하는 개발 하네스 만들기

Claude Code나 Codex를 이용해 개발하다 보면 꽤 묘한 경험을 하게 된다.

어제 분명히 해결했던 오류를 오늘 다시 설명해야 한다.
프로젝트에서 npm이 아니라 pnpm을 사용한다고 여러 번 말했는데 새 세션에서는 다시 확인해야 한다.
인증 코드를 수정할 때 반드시 건드리지 말아야 할 부분을 지난주에 발견했는데, 새로운 에이전트는 그 사실을 모른다.

모델이 성능이 부족해서 생기는 문제만은 아니다.

프로젝트에는 역사가 있지만, AI에게는 그 역사를 이어받을 구조가 없기 때문이다.

사람이 개발팀에 새로 합류하면 README를 읽고, 아키텍처 문서를 보고, 이전 장애 사례를 확인하고, 팀의 코드 리뷰 규칙을 배운다.

AI 에이전트도 마찬가지다.

그래서 최근에는 단순히 좋은 프롬프트를 만드는 것보다 AI가 프로젝트의 규칙, 지식, 경험을 계속 이어받을 수 있는 Agent Harness를 설계하는 것이 중요해지고 있다.

내가 생각하는 기본 구조는 다음과 같다.

사용자 요청
     │
     ▼
 AGENTS.md
     │
     ├── 공통 프로젝트 규칙
     ├── Agent 선택 기준
     ├── Skill 선택 기준
     └── Memory Index 위치
             │
             ▼
     작업 Context 구성
             │
      ┌──────┼─────────┐
      │      │         │
      ▼      ▼         ▼
 Current   관련       관련
 State    Memory     Docs
      │
      └──────┬─────────┘
             ▼
        적절한 Agent
             │
       ┌─────┴──────┐
       ▼            ▼
 Agent Memory      Skill
       │            │
       └─────┬──────┘
             ▼
          작업 실행
             │
             ▼
       Test / Build / Verify
             │
        ┌────┴─────┐
        │          │
      실패        성공
        │          │
        ▼          ▼
    다시 분석    결과 정리
                   │
             재사용할 발견?
                /      \
              NO        YES
              │          │
              ▼          ▼
             종료     Learning 후보
                          │
                       검증됨?
                       /    \
                     NO      YES
                     │        │
                     ▼        ▼
                  폐기/보류  Memory 기록
                              │
                        반복적/전역적?
                           /       \
                         NO         YES
                         │           │
                         ▼           ▼
                     Memory 유지   Rule 승격
                                   │
                              AGENTS.md
                              또는 rules/

처음 보면 조금 복잡해 보인다.

하지만 핵심은 의외로 단순하다.

AI가 작업한다 → 결과를 검증한다 → 재사용할 경험만 기억한다 → 반복적으로 중요한 경험은 프로젝트 규칙으로 승격한다.

이 흐름을 하나씩 살펴보자.

---

1. 시작점은 프롬프트가 아니라 AGENTS.md다

사용자가 이렇게 요청했다고 하자.

로그인하고 10분 정도 지나면 세션이 풀리는 문제가 있어. 고쳐줘.

일반적인 AI 코딩 환경에서는 바로 코드 검색부터 시작할 가능성이 높다.

하지만 프로젝트 하네스를 사용하는 환경에서는 먼저 AGENTS.md가 기준점이 된다.

AGENTS.md를 거대한 개발 문서로 만드는 것은 아니다.

오히려 프로젝트의 지도이자 라우터로 사용한다.

예를 들면 다음과 같다.

# Project Agent Guide

## Core Rules

- package manager는 pnpm을 사용한다.
- TypeScript strict mode를 유지한다.
- 기존 구조를 우선 재사용한다.
- 변경 후 관련 테스트를 실행한다.
- 검증되지 않은 추측을 프로젝트 메모리에 기록하지 않는다.

## Context

현재 상태:
docs/memory/current-state.md

Memory Index:
docs/memory/index.md

Architecture:
docs/architecture.md

## Agent Routing

아키텍처 / 대규모 구조 변경
→ architect

버그 / 오류 / 테스트 실패
→ debugger

테스트 설계 및 검증
→ tester

완료된 코드 검토
→ code-reviewer

## Skill Routing

새 기능 개발
→ feature-development

버그 분석
→ debugging

테스트
→ testing

코드 리뷰
→ code-review

배포
→ release

여기서 중요한 점은 AGENTS.md에 모든 지식을 집어넣지 않는다는 것이다.

AGENTS.md는 다음 질문에 답하면 된다.

이 프로젝트에서 무엇을 지켜야 하는가?

이 문제를 누가 맡아야 하는가?

어떤 작업 절차를 사용해야 하는가?

필요한 지식은 어디에 있는가?

즉 AGENTS.md는 백과사전이 아니라 AI용 프로젝트 내비게이션이다.

---

2. 모든 정보를 읽지 말고 필요한 Context만 구성한다

AI 에이전트를 오래 사용하다 보면 컨텍스트 관리가 매우 중요해진다.

아키텍처 문서 500줄, 과거 장애 기록 1,000줄, 개발 규칙 500줄, 이전 작업 로그 3,000줄을 모든 요청마다 모델에게 넣는 것은 좋은 방법이 아니다.

그래서 중간에 Memory Index를 둔다.

docs/
└── memory/
    ├── index.md
    ├── current-state.md
    ├── learnings.md
    ├── pitfalls.md
    ├── handoff.md
    └── agents/
        ├── architect.md
        ├── debugger.md
        ├── tester.md
        └── code-reviewer.md

index.md는 일종의 메모리 목차다.

# Project Memory Index

## Current Project Context

현재 상태
→ current-state.md

현재 작업 인수인계
→ handoff.md

## General Knowledge

검증된 프로젝트 학습
→ learnings.md

알려진 위험 요소
→ pitfalls.md

## Agent Memory

Architecture 관련 경험
→ agents/architect.md

Debug 관련 경험
→ agents/debugger.md

Testing 관련 경험
→ agents/tester.md

Code Review 관련 경험
→ agents/code-reviewer.md

로그인 버그라면 AI가 굳이 release 관련 기억이나 UI 디자인 문서를 읽을 이유가 없다.

대신 다음 정도만 읽으면 된다.

사용자 요청
   ↓
로그인 세션 문제
   ↓
Memory Index
   ↓
current-state.md
pitfalls.md
agents/debugger.md
architecture.md의 인증 관련 부분

이렇게 필요한 정보만 가져오는 방식을 사용하면 컨텍스트를 훨씬 효율적으로 사용할 수 있다.

---

3. Current State는 AI에게 프로젝트의 현재 시간을 알려준다

AI가 프로젝트에서 자주 실수하는 이유 중 하나는 코드만 보고 현재 상황을 추측하기 때문이다.

예를 들어 코드에는 로그인, OAuth, Refresh Token 관련 파일이 모두 존재할 수 있다.

하지만 실제 프로젝트 상태는 다음일 수 있다.

# Current State

Last Updated: 2026-09-28

## Completed

- Email Login
- Google OAuth
- User DB 저장

## In Progress

- Refresh Token Rotation

## Next

- Session Middleware
- Logout
- Authentication Integration Test

## Known Issue

Safari 환경에서 OAuth callback 간헐적 실패

이 문서 하나만 있어도 AI는 상당히 다른 판단을 한다.

코드 존재 여부만 보고

Refresh Token 구현되어 있네요.

라고 판단하지 않고,

코드 일부는 존재하지만 현재 구현 진행 중인 기능이다.

라는 컨텍스트를 가진다.

그래서 current-state.md는 일종의 프로젝트 체크포인트 역할을 한다.

---

4. Agent는 ‘누가 일할 것인가’를 결정한다

로그인 세션 문제가 들어왔다.

이제 AGENTS.md의 Routing 규칙에 따라 적절한 Agent를 선택한다.

이번에는 Debugger다.

User
 ↓
AGENTS.md
 ↓
Debugger

Debugger Agent는 단순한 프롬프트가 아니다.

이 에이전트의 역할과 사고 방식을 정의한다.

예를 들면 다음과 같다.

# Debugger

문제를 바로 수정하려고 하지 않는다.

항상 다음 순서를 따른다.

1. 문제 재현
2. 에러와 로그 수집
3. 관련 코드 추적
4. Root Cause 확인
5. 최소 변경
6. 테스트
7. Regression 확인

추측만으로 코드를 수정하지 않는다.

반복될 가능성이 있는 문제를 발견하면
Project Learning 후보로 제안한다.

Architect Agent는 전혀 다른 태도를 가져야 한다.

Tester도 다르다.

Reviewer도 다르다.

그래서 Agent는 이렇게 이해하면 쉽다.

Agent = 누가 이 문제를 해결할 것인가

---

5. Skill은 ‘어떻게 일할 것인가’를 정의한다

Agent와 Skill을 혼동하기 쉽다.

하지만 둘은 다른 개념이다.

Debugger는 역할이다.

Debugging은 작업 방법이다.

Debugger
   ↓
Debugging Skill

예를 들어 debugging/SKILL.md는 다음과 같이 만들 수 있다.

---
name: debugging
description: 버그, 오류, 테스트 실패를 조사할 때 사용
---

# Debugging Workflow

1. 문제를 재현한다.
2. 기대 결과와 실제 결과를 비교한다.
3. 에러 로그를 수집한다.
4. 변경 이력을 확인한다.
5. 관련 모듈을 좁힌다.
6. Root Cause를 확인한다.
7. 가능한 최소 범위로 수정한다.
8. 관련 테스트를 실행한다.
9. 전체 regression 여부를 확인한다.
10. 재사용 가능한 발견이 있는지 평가한다.

Agent와 Skill의 관계는 1:1이 아니다.

Debugger가 debugging, testing, database-investigation Skill을 사용할 수도 있다.

Architect가 architecture-analysis, migration-planning, security-review Skill을 사용할 수도 있다.

그래서 관계는 오히려 다음에 가깝다.

Agents
  ↕
Skills

Agent는 역할이고 Skill은 능력이다.

---

6. Agent에게도 경험이 필요하다

여기서 한 단계 더 나갈 수 있다.

Debugger가 과거에 이 프로젝트에서 어떤 문제를 만났는지 기억하게 하는 것이다.

docs/memory/agents/debugger.md

예를 들면 다음과 같다.

# Debugger Memory

## Authentication

### OAuth session disappearing

Symptom:
로그인 후 일정 시간이 지나면 session이 사라지는 문제가 있었다.

Root Cause:
middleware가 refresh cookie를 덮어쓰고 있었다.

Verified Fix:
refresh cookie를 보존하도록 middleware 수정.

Verification:
authentication integration tests 통과.

새로운 인증 문제가 발생하면 Debugger는 이 파일을 참고한다.

하지만 중요한 차이가 있다.

과거 해결책을 무조건 다시 적용하는 것이 아니다.

“과거에 이런 패턴이 있었다.”

라는 참고 정보를 가지는 것이다.

사람이 장애를 해결할 때도 비슷하다.

“지난번에도 Redis TTL 때문에 비슷한 장애가 났었는데?”

라고 기억하는 것과 같다.

---

7. 이제 실제 작업을 시작한다

이 시점에서 AI가 갖고 있는 컨텍스트는 상당히 좋아진다.

사용자 요청

+

프로젝트 Rules

+

Current State

+

관련 Architecture

+

Known Pitfalls

+

Debugger Memory

+

Debugging Skill

그리고 나서야 실제 코드를 조사한다.

Request
   ↓
Reproduce
   ↓
Logs
   ↓
Code Trace
   ↓
Root Cause
   ↓
Fix

이 차이가 중요하다.

기존 방식은:

질문
 ↓
코드 수정

에 가깝다.

Agent Harness 방식은:

질문
 ↓
Context
 ↓
Role
 ↓
Skill
 ↓
Evidence
 ↓
수정

이다.

---

8. 수정했다고 작업이 끝난 것이 아니다

AI 개발에서 특히 중요한 부분이다.

코드를 변경했다고 해서 해결된 것이 아니다.

반드시 검증 단계가 있어야 한다.

작업 실행
   ↓
Test
Build
Lint
Type Check
Integration Test
   ↓
Verify

프로젝트에 따라 검증 Skill을 따로 둘 수도 있다.

skills/
├── debugging/
├── testing/
└── code-change-verification/

예를 들어 버그를 고친 후:

pnpm test

pnpm lint

pnpm build

을 실행한다.

인증 문제라면 관련 integration test도 수행한다.

그리고 두 갈래가 생긴다.

Verify
  │
  ├─ 실패 → 다시 분석
  │
  └─ 성공 → 결과 정리

이 단계가 없으면 AI가 잘못된 수정 결과를 스스로 “학습”하는 위험이 생긴다.

---

9. 가장 중요한 단계는 ‘무엇을 기억하지 않을 것인가’다

작업에 성공했다고 모든 정보를 저장하면 안 된다.

예를 들어 다음과 같은 내용은 프로젝트 장기 기억으로 남길 가치가 거의 없다.

auth.ts 142번째 줄에서 오타 발견

변수명이 잘못되어 있었음

세미콜론 누락

임시 테스트 데이터 수정

반대로 이런 것은 다시 사용할 가능성이 높다.

middleware 수정 시 refresh cookie가 유지되어야 한다.

production 환경에서는 특정 environment variable이 필수다.

해당 외부 API는 retry 시 동일한 request id를 재사용하면 안 된다.

그래서 작업이 성공하면 이런 질문을 한다.

이 발견이
다른 작업에서도
다시 사용될 가능성이 있는가?

없다면 종료한다.

NO
 ↓
끝

있다면 Learning 후보가 된다.

---

10. Learning 후보라고 바로 Memory에 넣어서는 안 된다

이 단계가 전체 시스템에서 가장 중요하다고 생각한다.

AI가 이렇게 판단했다고 하자.

이 버그의 원인은 아마 middleware일 것이다.

이것은 아직 Learning이 아니다.

추측이다.

실제로 다음이 확인되어야 한다.

문제 재현

↓

middleware 수정

↓

문제 사라짐

↓

관련 테스트 통과

↓

원인과 수정 사이의 관계 확인

그제야 검증된 Learning이 된다.

Learning Candidate
       ↓
Verification
       ↓
Verified Learning

검증되지 않았다면 폐기하거나 임시 상태로 둔다.

Candidate
   │
   ├── Verified → Memory
   │
   └── Unverified → Discard / Pending

이 과정이 없는 AI 메모리 시스템은 상당히 위험하다.

AI가 잘못 추론한 내용을 스스로 저장하고 다음 세션에서 다시 참고하는 Memory Pollution이 발생할 수 있기 때문이다.

---

11. 검증된 경험만 Project Memory로 들어간다

검증이 끝난 내용은 learnings.md에 기록할 수 있다.

## L-023

Date: 2026-09-28
Status: VERIFIED
Scope: Authentication

### Problem

OAuth 로그인 후 일정 시간이 지나면
사용자 session이 사라짐.

### Root Cause

middleware가 refresh cookie를 덮어씀.

### Solution

refresh cookie를 유지하도록 middleware 수정.

### Verification

authentication integration test 통과.

### Confidence

HIGH

이 파일은 단순한 로그가 아니다.

프로젝트에서 실제로 검증된 경험의 데이터베이스다.

---

12. 하지만 Memory도 끝없이 쌓아서는 안 된다

시간이 지나면 프로젝트는 변한다.

Next.js 버전이 바뀌고 DB가 바뀌고 인증 구조도 바뀐다.

3년 전에 맞았던 Learning이 지금은 틀릴 수 있다.

그래서 Memory에도 Lifecycle이 필요하다.

ACTIVE
  ↓
SUPERSEDED
  ↓
ARCHIVED

예를 들어:

Status: SUPERSEDED
Superseded-By: L-078

같은 상태를 둘 수 있다.

이 구조가 있어야 AI가 오래된 프로젝트 경험을 현재 사실처럼 사용하는 것을 줄일 수 있다.

---

13. Memory가 반복되면 Rule로 승격한다

여기에서 시스템이 한 단계 더 발전한다.

다음 Learning이 여러 번 발생했다고 해보자.

Authentication middleware 수정
        ↓
refresh cookie 문제 발생

한 번이라면 learnings.md에 있으면 충분하다.

하지만 여러 작업에서 계속 문제가 발생한다면 이야기가 달라진다.

그때는 경험이 아니라 프로젝트 규칙이 된다.

Learning
   ↓
Learning
   ↓
Learning
   ↓
Pattern
   ↓
Rule

그리고 AGENTS.md 또는 관련 rule 파일로 승격한다.

예를 들면:

## Authentication Rule

middleware를 수정할 경우
refresh token cookie 보존 테스트를 반드시 실행한다.

이제 다음 Agent는 문제를 일으킨 뒤 해결 방법을 찾는 것이 아니라 처음부터 실수를 피한다.

바로 이 지점에서 프로젝트가 경험을 통해 조금씩 좋아진다.

---

14. 그래서 Memory에는 세 단계가 있다

전체 시스템을 단순화하면 기억은 세 단계로 나뉜다.

LEVEL 1

Session Memory
이번 작업에서만 필요한 정보

        ↓

LEVEL 2

Project Memory
검증된 프로젝트 경험

        ↓

LEVEL 3

Project Rule
반복적으로 중요한 규칙

예를 들어:

"로그인 문제가 발생했다."
        ↓
Session

"middleware가 cookie를 덮어쓰는 문제가 확인됐다."
        ↓
Project Memory

"Auth middleware 변경 시
cookie preservation test 필수."
        ↓
Project Rule

이 흐름을 Memory Promotion이라고 생각할 수 있다.

---

15. 최종 프로젝트 구조

실제 프로젝트에서는 다음과 같은 형태로 구성할 수 있다.

AI-PROJECT/
│
├── AGENTS.md
├── CLAUDE.md
│
├── skills/
│   ├── feature-development/
│   │   └── SKILL.md
│   ├── debugging/
│   │   └── SKILL.md
│   ├── testing/
│   │   └── SKILL.md
│   ├── code-review/
│   │   └── SKILL.md
│   └── release/
│       └── SKILL.md
│
├── .claude/
│   ├── rules/
│   ├── agents/
│   │   ├── architect.md
│   │   ├── debugger.md
│   │   ├── tester.md
│   │   └── code-reviewer.md
│   ├── skills/
│   └── settings.json
│
├── .codex/
│   ├── config.toml
│   └── agents/
│       ├── architect.toml
│       ├── debugger.toml
│       ├── tester.toml
│       └── code-reviewer.toml
│
├── docs/
│   ├── architecture.md
│   ├── decisions.md
│   ├── workflows.md
│   │
│   └── memory/
│       ├── index.md
│       ├── current-state.md
│       ├── learnings.md
│       ├── pitfalls.md
│       ├── handoff.md
│       │
│       ├── agents/
│       │   ├── architect.md
│       │   ├── debugger.md
│       │   ├── tester.md
│       │   └── code-reviewer.md
│       │
│       └── archive/
│
├── src/
├── tests/
└── README.md

각 영역의 역할을 한 문장씩만 기억하면 된다.

AGENTS.md
= 어디로 가야 하는가

Agent
= 누가 일하는가

Skill
= 어떻게 일하는가

Docs
= 프로젝트가 무엇인가

Memory
= 프로젝트가 무엇을 배웠는가

Tests
= 그 학습이 사실인지 증명하는 것

Rules
= 다시는 잊어서는 안 되는 것

---

16. 결국 만드는 것은 ‘AI의 기억’이 아니라 ‘프로젝트의 기억’이다

이 구조에서 가장 중요한 생각은 특정 AI 모델에게 기억을 주는 것이 아니다.

Claude Code만을 위한 기억도 아니다.

Codex만을 위한 기억도 아니다.

진짜 목표는:

프로젝트 자체가 기억을 갖게 만드는 것

이다.

오늘 Claude가 문제를 해결할 수 있다.

내일은 Codex가 이어서 개발할 수도 있다.

다음 달에는 더 좋은 새로운 AI 에이전트를 사용할 수도 있다.

하지만 프로젝트의:

Rules

Architecture

Decisions

Skills

Current State

Pitfalls

Learnings

Handoff

가 Git Repository 안에 남아 있다면 AI가 바뀌어도 경험은 사라지지 않는다.

Claude
     ↘

Codex → Project Memory ← Future Agent

     ↗
Human

AI 모델을 중심으로 개발 환경을 설계하는 대신 Repository를 중심으로 AI 개발 시스템을 설계하는 것이다.

---

17. 이 구조가 흥미로운 이유

지금까지 AI 코딩 도구의 성능 경쟁은 대부분 모델 자체에 집중되어 있었다.

더 큰 모델.

더 긴 Context Window.

더 좋은 Reasoning.

더 많은 Tool.

물론 중요하다.

하지만 실제 장기 프로젝트에서는 다른 질문이 점점 중요해질 것 같다.

이 AI는 얼마나 똑똑한가?

뿐만 아니라,

이 프로젝트에서 지난 6개월 동안 우리가 무엇을 배웠는지 알고 있는가?

이다.

강력한 모델이 매번 처음부터 프로젝트를 분석하는 것보다, 적당히 강력한 모델이 프로젝트의 과거 결정과 실패 경험을 정확히 이어받는 편이 더 나을 때도 있다.

그래서 앞으로 코딩 에이전트의 중요한 인프라는 단순한 Prompt Engineering에서 한 단계 더 나아가,

Context Engineering

+

Agent Routing

+

Skill System

+

Project Memory

+

Verification

+

Memory Promotion

이 결합된 형태가 되지 않을까 생각한다.

---

마무리

전체 구조를 다시 한 번 압축하면 다음과 같다.

사용자 요청
       ↓
AGENTS.md
       ↓
필요한 Context 검색
       ↓
Agent 선택
       ↓
Agent Memory
       +
Skill
       ↓
작업
       ↓
Test / Verification
       ↓
재사용 가능한 발견
       ↓
Verified Learning
       ↓
Project Memory
       ↓
반복적인 Pattern
       ↓
Project Rule

여기서 AI 모델 자체는 학습되지 않는다.

모델의 가중치를 바꾸는 것도 아니다.

그 대신 프로젝트가 경험을 축적한다.

그리고 다음 AI 에이전트는 그 경험 위에서 다시 시작한다.

결국 좋은 AI 개발 환경이란 매번 더 좋은 모델을 부르는 것만이 아니라,

어제 해결한 문제를 오늘 다시 처음부터 해결하지 않아도 되는 환경

을 만드는 것이 아닐까.

그게 내가 생각하는 Project Memory 기반 Agent Harness다.