# Mirror Context

**context 관리를 위한 개인적인 생각**

## 🚀 시작

어느 순간부터 이런 생각이 들었습니다.  
이제는 개발에서도 AI사용이 많아지는 만큼, context를 다루는 일이 중요해지고 있는 것 아닐까 하는 생각이었습니다.

사실 이 글은 검증된 방식이나, 충분히 실험해본 뒤 정리하는건 아닙니다.  
어느 날 문득, “이제는 결국 자연어로 개발하고 문서로 관리하지 않을까?” 하는 생각이 들었고, 그 생각을 따라가다 보니 여기까지 오게 되었습니다.

그래서 이 글은 어떤 방법을 확정해서 설명하는 글이라기 보다, 아직 검증되지는 않았지만 문서로 관리한다는 생각을 구체화한 글에 가깝습니다.  
실제로 좋은 방식인지, 현실적으로 유지 가능한 구조인지, 실무 개발자 분들이 보시기에 아쉬운 부분이 있을지도 모르지만

지금 시점에서 한번 글로 정리해보고 싶었습니다.

## ☁️ 꿈

AI를 활용한 개발은 새로운 세상을 열어주었습니다.  
이전에는 사람이 직접 코드를 읽고, 구조를 이해하고, 수정 범위를 판단하고, 문서를 찾아보며 하나씩 이어 붙이던 일들을 이제는 AI가 빠르게 도와줄 수 있게 되었습니다.

그런데 바로 그 지점에서 오히려 다른 문제가 보이기 시작했습니다.  
제가 이해한 ai는 멍청했습니다. 기억하지 못하는 존재입니다.

비유를 해보자면 사고로 매일매일 기억을 잃는 사람과 같습니다. 영화난 드라마를 보면 그 사람들은 아침마다 어제, 과거에 일들을 다 읽고 하루를 시작합니다.  
AI도 마찬가지입니다. 항상 새로운 대화를 시작할때 과거 내용을 다 읽어야 합니다. 그리고 읽은 이후에 사용자의 질문에대한 답을 합니다.  
하지만 문제가 하나 있습니다. ai가 읽어야하는 내용이 너무 많다면 ai는 읽다가 머리가 터질수도 있습니다. 그래서 "컨텍스트 엔지니어링"이 나왔다고 생각합니다.  
과거 이야기를 긴이야기라고 ai가 어떻게 잘 빠르게 읽을 수 있게 하냐가 중요해 진것 같습니다.  

그래서 이 아이디어가 들었습니다.  
보통개발을 하며 AI를 사용할때 그냥 사용하게 된다면 ai는 단순히 코드를 읽고 이 프로젝트를 이해할 것입니다.  

왜 이 구조가 만들어졌는지,  
왜 이 책임 분리가 필요했는지,  
무엇을 수정하면 어디까지 함께 봐야 하는지,  
이전에 비슷한 시도를 했다가 왜 멈추었는지,  
지금의 형태가 어떤 판단의 결과물인지.  

하지만 이런 것들은 코드에 온전히 남아 있지 않습니다.  
이런것들은 사람의 기억 속에서만이어지고 ai는 알수 없습니다. 사람은 항상 이러한 것들을 ai에게 계속해서 설명을 해줘야 합니다.  

결국 프로젝트가 커질수록 context를 잘파악해야 한다는 생각이 들었습니다.

Mirror Context의 시작은 이러한 context에 대한 고민에서 시작하였고  
어떤 AI가 언제든 들어와도 같은 구조와 같은 판단의 흔적을 읽을 수 있도록 하는것이 목표입니다.

## 🪞 Mirror Context

이 방식은 단순합니다.  
**코드 구조에 대응되는 문서 구조를 함께 두고, 그 문서 구조 자체를 프로젝트의 context 저장소로 삼아보자는 것**입니다.

프로젝트 밖에서 따로 존재하는 것이 아니라, 코드와 같은 형태와 같은 위치 감각을 가지며 프로젝트 안에서 함께 존재 한다는 점입니다.  
단순히 사람이 읽기 좋은 문서가 아니라, ai의 뇌의 역할을 해주는 문서가 됩니다.

기존의 컨텍스트 관리는 보통 `README`, `RULES.md`, `ARCHITECTURE.md`, `CONVENTION.md` 같은 전역 문서를 중심으로 이루어졌습니다.  
이런 방식은 프로젝트 전체의 방향과 원칙을 설명하는 데에는 분명 유용합니다.  
하지만 실제 개발이 일어나는 파일 단위의 맥락까지 붙잡아두기에는 한계가 있다고 느꼈습니다.

그래서 저는 이 문제를 해결하고 싶었습니다.  
프로젝트를 설명하는 상위 문서만 두는 것이 아니라, **코드 구조 자체에 대응하는 문서 구조를 함께 두는 방식**을 생각하게 되었습니다.

## 🤔 이게 뭔데?

Mirror Context는 프로젝트를 설명하는 문서를 조금 더 잘 정리하자는 생각에서 출발한 구조가 아닙니다.  
오히려 그 반대에 가깝습니다. 기존의 컨텍스트 관리는 보통 `README`, `ARCHITECTURE.md`, `RULES.md`, `CONVENTION.md` 같은 전역 문서를 중심으로 이루어졌고  
저도 처음에는 그런 방식이 기본이라고 생각했습니다.

그런데 개발은 전역 문서 안에서 일어나는 것이 아니라, 결국 폴더와 파일 안에서 일어납니다.  
실제 수정과 판단은 특정 파일에서 이루어지고, 문제도 대부분 파일 단위에서 생깁니다.    
그런데 전역 문서만으로는 그 위치의 맥락까지 충분히 남기기 어렵다고 느꼈습니다. 

예를 들어 실제 코드 구조가 아래와 같다고 하겠습니다.

```text
backend/
├── src/
│   ├── api/
│   │   ├── userController.ts
│   │   └── authRoutes.ts
│   ├── services/
│   │   └── authService.ts
│   ├── models/
│   │   └── userModel.ts
│   └── utils/
│       └── validator.ts
├── config/
└── tests/
```

기존 방식에서는 이 구조 위에 README나 아키텍처 문서, 규칙 문서 같은 상위 문서가 얹히는 식이 많습니다.  
이런 방식은 프로젝트 전체의 방향을 설명하는 데에는 분명 도움이 됩니다.  
하지만 `userController.ts`가 왜 이렇게 생겼는지, `authService.ts`를 고치면 어디까지 함께 봐야 하는지, 이 파일을 만들 때 어떤 계획이 있었는지, 예전에 어떤 시도가 있었고 왜 잘되지 않았는지까지는 잘 남지 않습니다.

**코드 구조 자체에 대응하는 문서 구조를 따로 만드는 방식**을 생각하게 되었습니다.  
즉 프로젝트를 설명하는 문서에서 멈추는 것이 아니라, **프로젝트를 구성하는 코드 단위와 같은 해상도의 문서 구조**를 함께 두는 것입니다.

```text
mirror_docs/
├── backend/
│   ├── EPIC.md
│   ├── src/
│   │   ├── EPIC.md
│   │   ├── api/
│   │   │   ├── EPIC.md
│   │   │   ├── userController.md
│   │   │   ├── userControllerPlan.md
│   │   │   ├── authRoutes.md
│   │   │   └── authRoutesPlan.md
│   │   ├── services/
│   │   │   ├── EPIC.md
│   │   │   ├── authService.md
│   │   │   └── authServicePlan.md
│   │   ├── models/
│   │   │   ├── EPIC.md
│   │   │   ├── userModel.md
│   │   │   └── userModelPlan.md
│   │   └── utils/
│   │       ├── EPIC.md
│   │       ├── validator.md
│   │       └── validatorPlan.md
│   ├── config/
│   │   └── EPIC.md
│   └── tests/
│       ├── EPIC.md
│       ├── userController.test.md
│       └── authService.test.md
├── RULES.md
├── CONVENTION.md
├── ARCHITECTURE.md
├── GLOBAL_PLAN.md
├── INDEX.md
├── MAP.md
├── TEST_REPORT.md
├── LEARNINGS.md
└── DEBUG_LOG.md
```

여기서 핵심은 전역 문서가 있다는 사실이 아닙니다.   
진짜 핵심은 **문서가 코드와 위치적으로 대응된다는 점**입니다.

- 폴더에는 폴더 단위의 맥락을 담는 `EPIC.md`
- 파일에는 파일과 대응되는 설명 문서
- 파일 근처에는 그 파일을 위한 계획 문서
- 테스트, 실패, 디버그 기록은 프로젝트 전체의 기억 문서
- 전역 문서는 이 모든 구조의 기준점

즉 Mirror Context는 문서를 한곳에 모아두는 방식이 아니라, **프로젝트의 코드 구조를 문서 구조로 한 번 더 비추는 방식**입니다.

## 여기서 문서 무엇을 하는가

이 구조에서 문서는 단순한 설명서가 아닙니다.   
문서는 사람이 읽기 위한 참고 자료이기도 하지만, 동시에 AI가 프로젝트를 이해하기 위한 **첫 번째 진입점**이 됩니다.

기존 방식에서는 AI가 코드를 직접 많이 읽으면서 프로젝트를 이해하려고 합니다.  
하지만 프로젝트가 커질수록 이 방식은 무거워질 수 있습니다.  
코드만 읽어서는 구조는 보일 수 있어도, 그 구조의 이유나 판단 배경까지 충분히 드러나지 않는 경우가 많기 때문입니다.

Mirror Context에서는 흐름을 조금 바꿔봅니다.

1. AI가 먼저 대응 문서를 읽습니다.
2. 문서를 통해 구조, 책임, 연결 관계, 계획, 실패 이력을 파악합니다.
3. 실제 구현이나 수정이 필요한 순간에만 코드를 직접 읽습니다.

즉 문서는 단순한 요약이 아니라, AI가 프로젝트에 들어오기 전에 먼저 읽는 context가 됩니다.

여기서 중요한 것은 문서의 성격입니다.  
Mirror Context에서 문서는 요약문이라기보다 정리문에 더 가깝습니다.

요약은 정보를 줄이는 일입니다.  
핵심만 남기고 나머지를 덜어냅니다.  
반면 정리는 정보를 구조화하는 일입니다.  
무엇이 중요한지 말할 뿐 아니라, 어디를 더 읽어야 하는지, 어떤 코드와 연결되는지, 어떤 상위 문서를 먼저 봐야 하는지 등을 함께 남깁니다.

프로젝트의 맥락을 유지한다는 것은 결국 **정리**에 더 가까운 일이라고 생각했습니다.

중요한 것은 문장을 짧게 만드는 것이 아니라, 이해의 경로를 잃지 않게 만드는 것입니다.
그래서 Mirror Context에서는 문서가 많아질 수밖에 없습니다.
그리고 아마 실제로도 많아질 것입니다.

하지만 맥락을 붙잡는다는 것은 원래 압축보다 구조화에 가까운 일인지도 모릅니다.
문서가 늘어나는 것 자체보다 더 중요한 것은, 그 문서들이 서로 엉키지 않고 올바른 위치와 역할을 갖는 일입니다.

### 1. 전역 시스템 문서 (Global Context)

프로젝트 전체의 규칙과 구조를 정의하는 문서입니다. 모든 AI 에이전트가 공통으로 읽는 **프로젝트의 기본 기준**입니다.

#### RULES.md

AI 에이전트가 작업할 때 지켜야 할 **협업 규칙과 안전 기준**을 정의합니다.   
예를 들어 사용자 승인 기준, 오류 발생 시 재시도 규칙, 위험한 작업에 대한 제한 등을 포함합니다.  
AI가 자율적으로 작업하되 **프로젝트의 안전선을 넘지 않도록 하는 장치**입니다.

#### CONVENTION.md

프로젝트에서 사용하는 **코드와 문서 작성 규칙**을 정의합니다.  
네이밍 규칙, 커밋 메시지 형식, Markdown 구조 등을 정해 **모든 AI가 같은 스타일로 작업하도록** 합니다.

#### ARCHITECTURE.md

프로젝트의 **기술 구조와 설계 의도**를 설명합니다.  
사용 기술 스택, 주요 모듈 구조, 폴더 설계 이유 등을 기록하여 새로운 AI가 투입되어도 **전체 구조를 빠르게 이해할 수 있도록** 합니다.

### 2. 네비게이션 및 흐름 문서 (Navigation Context)

프로젝트 안에서 AI가 길을 잃지 않도록 돕는 **지도 역할의 문서들**입니다.

#### GLOBAL_PLAN.md

프로젝트의 **현재 작업 상태**를 기록합니다.  
어떤 브랜치에서 어떤 작업이 진행 중인지, 어떤 에이전트가 무엇을 하고 있는지 등을 정리하여 **작업 충돌을 방지**합니다.

#### INDEX.md

프로젝트의 **파일과 기능을 연결하는 구조 지도**입니다.  
AI가 특정 기능을 수정해야 할 때 **어떤 파일을 찾아야 하는지 빠르게 찾도록** 돕습니다.

#### MAP.md

프로젝트 내부 요소들의 **의존 관계**를 정리합니다.  
예를 들어 특정 함수나 모듈을 수정할 때 **어디에 영향이 가는지 사전에 파악할 수 있도록** 합니다.

### 3. 구현 단계 문서 (The Blueprint)

실제 기능을 구현할 때 사용하는 **작업 지시 문서**입니다.

#### EPIC.md

하나의 **Epic 기능의 최종 목표와 요구사항**을 정의합니다.  
즉, 이 기능이 **무엇을 만들어야 하는지**를 설명하는 문서입니다.

#### PLAN.md

SPEC을 기반으로 작성되는 **구현 계획 문서**입니다.  
최소구현 단위로 생성되며 어떤 작업을 어떤 순서로 구현할지 정리합니다.

### 4. 품질 및 히스토리 문서 (The Archive)

결과를 검증하고 작업 과정에서 얻은 경험을 기록하는 문서입니다.

#### TEST_REPORT.md

최종 결과물의 **품질 검사 보고서**입니다.  
빌드 결과, 테스트 통과 여부, 실행 로그 등을 기록합니다.

#### LEARNINGS.md

AI가 작업 과정에서 겪은 **실패와 교훈을 정리한 문서**입니다.  
여러 번의 실패 끝에 성공했더라도 그 과정에서 얻은 경험을 남겨 **같은 실수를 반복하지 않도록** 합니다.

#### DEBUG_LOG.md

에이전트 작업 과정의 **원본 기록**입니다.  
문제가 발생했을 때 원인을 추적하기 위한 **작업 블랙박스** 역할을 합니다.

## ⚰️ 끝

**Mirror context는 AI 시대에 프로젝트의 기억을 어디에, 어떤 형태로 남겨야 하는가**에 대한 하나의 생각입니다.   
코드가 프로젝트를 실행하게 만든다면, 문서는 프로젝트를 이해할 수 있게 만듭니다.   
그리고 이해를 위한 문서들이 코드와 나란히, 같은 구조로 존재할 때 AI와 사람 모두 같은 context를 유지할 수 있지 않을까 생각했습니다.

이 방식은 아직 생각의 단계입니다.   
실제로 충분히 검증해본 것도 아니고, 운영해보면서 장단점을 확인한 것도 아닙니다.   
어쩌면 실제 프로젝트에 적용해보면 생각보다 너무 무겁거나, 유지 비용이 크거나, 다른 방식이 더 낫다는 결론이 나올 수도 있습니다.

그래도 지금 시점에서 적어도 하나는 분명하게 느껴졌습니다.   
AI를 개발에 깊게 자주 사용수록, 프로젝트의 품질을 좌우하는 것은 단순한 생성 능력만이 아니라 맥락을 어떻게 붙잡아두느냐의 문제라는 점입니다.

Mirror Context는 바로 그 문제를 해결하기 위한 도전중 하나 입니다.