Mirror Context

A personal idea about context management

🚀 Beginning

At some point, I started thinking about this.
Now that AI usage in development is increasing, maybe handling context is becoming more important.

To be honest, this is not a verified method, nor is it something I organized after extensive experimentation.
One day I suddenly thought, “In the end, won’t we develop with natural language and manage through documents?” and by following that thought, I ended up here.

So this is not really a document that explains a confirmed method. Rather, it is closer to a document that gives concrete shape to the idea of managing with documentation, even though it is not yet verified.
I do not know whether this is truly a good approach, whether this structure is realistically sustainable, or whether working developers may find parts of it lacking.

Still, at this point, I wanted to organize it in writing once.

☁️ Dream

AI-assisted development has opened a new world.
Tasks that people used to do one by one - reading code directly, understanding structure, judging the scope of changes, searching documents, and connecting everything together - can now be helped quickly by AI.

But at that very point, I started seeing a different problem instead.
The AI as I understand it was not smart. It is an entity that cannot remember.

To make an analogy, it is like a person who loses their memory every day due to an accident. In movies or dramas, those people start each morning by reading everything that happened yesterday and in the past.
AI is the same. Whenever it starts a new conversation, it has to read all prior content. And after reading, it answers the user’s question.
But there is one problem. If there is too much for AI to read, its head might explode while reading. I think that is why “context engineering” emerged.
It seems to have become important how AI can read long past stories well and quickly.

So this idea came to me.
When we use AI in regular development, if we just use it as-is, AI will simply read code and understand the project.

Why this structure was created,
why this separation of responsibilities was necessary,
if something is modified, how far you need to review together,
why a similar attempt in the past stopped,
what judgment led to the current form.

But these things are not fully left in the code.
These things live only in human memory, and AI cannot know them. People always have to keep explaining these things to AI.

In the end, I felt that as projects grow, understanding context well becomes critical.

Mirror Context started from this concern about context,
and its goal is to let any AI that comes in at any time read the same structure and traces of the same judgments.

🪞 Mirror Context

This method is simple.
Keep a document structure that corresponds to the code structure, and treat that document structure itself as the project’s context repository.

The key is that it does not exist separately outside the project; it exists together inside the project with the same form and the same sense of location as the code.
It is not merely documentation that is easy for people to read, but documentation that acts as AI’s brain.

Existing context management usually centered on global documents such as README, RULES.md, ARCHITECTURE.md, and CONVENTION.md.
This approach is certainly useful for explaining the overall direction and principles of a project.
But I felt it has limits in preserving file-level context where real development actually happens.

So I wanted to solve this problem.
Rather than keeping only high-level documents that explain the project, I began to think about also maintaining a document structure that corresponds to the code structure itself.

🤔 What is this?

Mirror Context did not start from the idea of just organizing project documents a bit better.
If anything, it is closer to the opposite. Existing context management typically centered on global documents like README, ARCHITECTURE.md, RULES.md, and CONVENTION.md,
and I initially thought that was the default approach too.

But development does not happen inside global documents; in the end, it happens inside folders and files.
Actual modifications and judgments are made in specific files, and most problems also occur at the file level.
And I felt that with only global documents, it is hard to preserve the context of that location sufficiently.

For example, assume the actual code structure looks like this.

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

In the existing approach, high-level documents such as README, architecture docs, and rule docs are often placed on top of this structure.
This certainly helps explain the overall direction of a project.
But why userController.ts looks like this, how far you should review together when changing authService.ts, what plan existed when this file was created, what attempts were made in the past and why they failed - these details are not preserved well.

So I started thinking about a method that creates a document structure corresponding to the code structure itself.
In other words, instead of stopping at documents that explain the project, maintain a document structure with the same granularity as the code units that compose the project.

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

The core point here is not the fact that global documents exist.
The real core point is that documents correspond to code spatially.

• EPIC.md for folder-level context in folders
• Explanatory documents corresponding to files
• Planning documents near each file for that file
• Project-wide memory documents for tests, failures, and debug records
• Global documents as the reference point for all of this structure

In other words, Mirror Context is not a way to gather documents in one place; it is a way to mirror the project’s code structure once more as a document structure.

What do documents do here?

In this structure, documents are not just manuals.
Documents are references for people to read, but at the same time they become the first entry point for AI to understand the project.

In the existing approach, AI tries to understand the project by reading a lot of code directly.
But as projects grow, this approach can become heavy.
Because reading only code may reveal structure, but often does not sufficiently reveal the reasons behind that structure or the background of judgments.

Mirror Context changes this flow a little.

1. AI first reads the corresponding documents.
2. Through those documents, it identifies structure, responsibilities, connections, plans, and failure history.
3. It reads code directly only when real implementation or modification is needed.

In short, documents are not just summaries; they become context that AI reads first before entering the project.

What matters here is the nature of the documents.
In Mirror Context, documents are closer to organized records than to summaries.

Summarizing is reducing information.
It keeps only the core and removes the rest.
Organizing, in contrast, is structuring information.
It not only says what is important, but also leaves where to read further, which code it connects to, and which higher-level documents to read first.

I thought maintaining project context is ultimately closer to organizing.

What is important is not making sentences short, but making sure we do not lose the path of understanding. That is why in Mirror Context, documents inevitably increase. And in reality, they probably will increase.

But maybe preserving context is originally closer to structuring than compressing. More important than the documents increasing is that those documents do not tangle with each other and have the right location and role.

1. Global System Documents (Global Context)

These are documents that define project-wide rules and structure. They are the project’s default baseline that all AI agents read in common.

RULES.md

Defines the collaboration rules and safety standards that AI agents must follow when working.
For example, it includes user approval criteria, retry rules when errors occur, and restrictions on risky operations.
It is a mechanism that lets AI work autonomously while not crossing the project’s safety boundaries.

CONVENTION.md

Defines the code and documentation writing rules used in the project.
It sets naming rules, commit message formats, Markdown structure, and so on, so that all AI agents work in the same style.

ARCHITECTURE.md

Explains the project’s technical structure and design intent.
It records the tech stack used, the structure of key modules, and why folders are designed the way they are, so that even a newly assigned AI can quickly understand the overall structure.

2. Navigation and Flow Documents (Navigation Context)

These are map-like documents that help AI not get lost inside the project.

GLOBAL_PLAN.md

Records the project’s current work status.
It organizes what work is in progress on which branch and which agent is doing what, thereby preventing work conflicts.

INDEX.md

This is a structure map that connects files and features in the project.
When AI needs to modify a specific feature, it helps it quickly find which files to look for.

MAP.md

Organizes the dependency relationships of internal project elements.
For example, when modifying a specific function or module, it helps you identify impact scope in advance.

3. Implementation-Stage Documents (The Blueprint)

These are work instruction documents used when implementing actual features.

EPIC.md

Defines the final goal and requirements of one epic feature.
In other words, it is a document explaining what this feature should produce.

PLAN.md

This is an implementation planning document written based on the SPEC.
It is created in minimum implementation units and organizes what to implement in what order.

4. Quality and History Documents (The Archive)

These documents validate results and record lessons obtained during work.

TEST_REPORT.md

This is a quality inspection report for the final output.
It records build results, test pass/fail status, and execution logs.

LEARNINGS.md

This is a document where AI organizes failures and lessons learned during work.
Even if it succeeds after multiple failures, it preserves that experience so that the same mistakes are not repeated.

DEBUG_LOG.md

This is the raw record of the agent work process.
It serves as a work black box for tracing causes when problems occur.

⚰️ End

Mirror Context is one idea about where and in what form project memory should be left in the AI era.
If code makes a project run, documents make a project understandable.
And I thought that when documents for understanding exist alongside code in the same structure, both AI and humans may be able to maintain the same context.

This approach is still at the idea stage.
It has not been sufficiently validated in practice, and its pros and cons have not yet been verified through operation.
Perhaps if applied to a real project, it may prove heavier than expected, costly to maintain, or lead to the conclusion that another approach is better.

Still, at least one thing felt clear at this point.
The more deeply and frequently we use AI in development, the more project quality is determined not only by generation capability but by how we preserve context.

Mirror Context is one ongoing challenge to solve exactly that problem.

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 같은 전역 문서를 중심으로 이루어졌고
저도 처음에는 그런 방식이 기본이라고 생각했습니다.

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

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

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

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

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

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는 바로 그 문제를 해결하기 위한 도전중 하나 입니다.