2025년 이전에 내가 AI를 사용할 때는 작업하던 내용을 일부 넘겨주고 하고 싶은 작업을 프롬프트로 계속 설명하는 방식에 가까웠다.

그때의 AI 사용은 매번 새로 시작하는 느낌이었다. 내가 알고 있는 맥락을 다시 설명하고 작업 방향을 다시 잡고 이전에 했던 판단을 다시 떠올리게 해야 했다. 그러다 보니 어느 순간부터는 코드를 작성하는 것보다 맥락을 전달하는 일이 더 신경 쓰이기 시작했다.

2026년 1월의 나는 AI를 이용해 개발하는 것을 넘어서 AI와 함께 일하면서 불편한 부분들을 자동화하고 개선해보기로 마음먹었다. 그중 하나가 Context 관리였다.

Logging

처음에는 단순하게 생각했다. AI는 새 세션이 시작되면 이전 내용을 잊어버리니 내가 알고 있는 내용을 최대한 많이 남겨두면 된다고 생각했다. 프로젝트의 방향, 작업한 내용, 문제를 해결한 방법, 주의해야 할 점들을 문서로 남겨두면 AI가 다시 작업을 이어갈 때 덜 헤맬 것 같았다.

실제로 해보니 기억을 남기는 것과 기억이 읽히는 것은 다른 문제였다.

처음에는 AI 에이전트를 위한 컨텍스트 엔지니어링: Manus 구축에서 얻은 교훈과 Planning with Files: Manus 방식으로 AI 에이전트 컨텍스트 문제 해결하기 - Geek News에서 아이디어를 얻어 tasks, findings, progress 같은 파일을 만들고, 작업 시작 전후로 AI가 기록을 읽고 갱신하도록 했다.

작업 전에는 task 파일과 progress를 확인하고 기술 조사가 필요하면 findings를 남기고 작업이 끝나면 progress를 갱신하는 식이었다.

내가 직접 다시 읽기에도 편했고 AI에게도 "이전 작업을 보고 이어서 해줘"라고 말할 수 있었다. 기록이 생긴다는 것만으로도 프로젝트가 조금 더 안정적으로 굴러가는 느낌이 있었다.

개선 사항

1. Context 오염 방지 (in Monorepo)

하지만 프로젝트가 커지면서 다른 문제가 생겼다.

내 프로젝트는 monorepo 구조로 되어 있다. client와 server가 있고 그 둘을 관리하는 workspace도 따로 있다. 세 영역의 작업 기록이 함께 쌓이다 보니 파일이 금방 커졌다. Context를 관리하려고 만든 기록이 다시 Context를 무겁게 만드는 상황이 된 것이다.

그래서 기록을 docs/client, docs/server, docs/workspace로 나누었다. 영역별로 기록을 분리하니 내가 직접 읽을 때도 편했고 AI에게 필요한 범위만 보게 하기에도 좋았다. 모든 기록을 한곳에 몰아넣는 것보다 지금 어떤 영역에서 작업하고 있는지 먼저 정하고 그 영역의 기록만 읽는 편이 더 낫다고 느꼈다.

물론 이것도 완벽하지는 않았다. 영역을 나누다 보니 다른 영역의 findings나 progress를 참조하지 못하는 경우가 생겼다. 그럴 때는 결국 내가 직접 "이쪽 기록도 봐야 한다"고 방향을 잡아줘야 했다. 기록 시스템을 만들었다고 해서 판단까지 모두 자동으로 해결되는 것은 아니었다.

2. Indexing

처음에는 findings.md, progress.md처럼 하나의 파일에 계속 내용을 쌓았다. 그런데 시간이 지날수록 파일이 커졌고 읽는 데 드는 비용도 커졌다. 모든 정보에 접근할 수 있다는 점은 좋았지만 매번 모든 내용을 읽어야 한다면 Context 관리라는 목적과는 조금 어긋난다고 느꼈다.

그래서 findings.index.md, progress.index.md를 두고 실제 내용은 findings/, progress/ 안의 개별 파일로 나누었다. 인덱스에는 어떤 기록이 있는지 요약만 남기고 필요한 경우에만 세부 파일을 읽도록 했다. 사람이 읽기에도 좋았고 전체 흐름은 인덱스에서 보고 필요한 내용만 골라 들어갈 수 있었다.

하지만 이 방식에도 단점은 있었다. 인덱싱 이후 AI가 findings를 적극적으로 참조하는 힘은 조금 약해진 것 같았다. 예전에는 오류 해결 방법이나 프로젝트의 주의점을 findings에서 알아서 찾아보는 경우가 있었는데 인덱스를 둔 뒤에는 연관성이 없다고 판단하고 지나치는 경우도 있었다.

그럴 때는 결국 내가 다시 지시해야 했다. 기록을 잘게 나누면 Context는 가벼워지지만 필요한 기록까지 도달하는 경로는 더 중요해지는데 이 균형이 생각보다 쉽지 않았다.

3. 기록 시스템

기록 시스템 자체에 대한 고민도 있었다.

Markdown 파일은 AI가 읽고 수정하기 좋다. 그래서 처음에는 자연스럽게 문서를 파일로 관리했다. 그런데 여러 AI를 동시에 실행시키고 각각이 기록을 남기게 하다 보니 같은 파일을 동시에 수정하는 문제가 생겼다. 또 AI Workspace 안의 Skill, Docs, Script를 AI를 통해 수정하다 보니 이 작업들이 믿을 수 있게 남아야 한다는 생각도 들었다.

그래서 workspace도 Git으로 관리하기 시작했다.

Git으로 관리하니 어떤 작업에서 무엇이 바뀌었는지 commit으로 확인할 수 있었고 잘못 작업하더라도 되돌릴 수 있었다. 동시에 접근하면서 생기는 문제도 어느 정도 자연스럽게 줄었다. 기록도 코드처럼 변경 이력을 남기고 검토할 수 있게 된 것이다.

물론 번잡함은 생겼다. server나 client 작업을 마친 뒤에도 workspace 쪽 문서를 commit, push, PR, merge까지 처리해야 하는 흐름이 생겼다. 그래서 docs branch를 따로 두고 각 작업 이후에는 그쪽에 기록을 쌓은 다음 나중에 한 번에 main으로 merge하는 방식으로 바꾸었다.

이것도 완벽한 해결책은 아니었다. 내가 직접 merge하고 pull하지 않으면 AI가 최신 docs를 참조하지 못하는 문제가 있었다. 하지만 이 프로젝트에서는 그 정도의 불편함은 감수할 수 있었다. 모든 계획의 방향성 결정은 아직 내가 하고 있었고 내가 흐름을 알고 있는 상태에서는 큰 문제가 되지 않았다.

만약 내가 새로운 프로젝트에서 기록 시스템을 도입한다면, 외부 시스템을 쓸 수도 있고 file locking만 도입할 수도 있다. 반대로 다시 Git을 쓸 수도 있다.

어떤 방식에 문제가 있다고 해서 모든 상황에서 틀린 방식이 되는 것은 아니다. 어떤 상황에서는 그 문제가 별 문제가 아니게 될 수도 있다.

지금 돌아보면

이번 프로젝트를 하면서 문서에 대한 생각이 조금 바뀌었다.

예전에는 문서를 나중에 사람이 읽는 설명서에 가깝게 생각했다. 왜 이런 결정을 했는지 남기고, 어떤 작업을 했는지 기록하고, 언젠가 돌아봤을 때 이해하기 위한 자료라고 생각했다.

AI를 이용해 개발하면서는 그 역할이 조금 달라졌다.

문서는 AI가 다음 행동을 결정하기 전에 읽는 입력값이 된다. 그러면 좋은 문서는 단순히 자세한 문서가 아니다. 지금 필요한 판단을 흐리지 않는 문서여야 한다. 많이 적는 것보다 어디까지 읽어야 하는지를 정해주는 것이 더 중요해진다.

tasks, progress, findings라는 구분도 그 자체가 중요한 것은 아니었다. 중요한 것은 각각의 문서가 어떤 질문에 답해야 하는지였다. 지금 해야 할 일은 무엇인지, 이전에 무엇을 했는지, 문제를 해결할 때 참고해야 할 사실은 무엇인지, 그 질문에 맞게 문서가 놓여 있어야 했다.

정보를 잃어버리지 않는 것도 중요하지만 호율적으로 다시 꺼내 읽을 수 있어야 의미가 있다.

결국 Context 관리는 AI의 발전에 용량이 늘어나고 효율적으로 압축하는 것뿐만이 아닌 잘 구성된 시스템으로도 할 수 있다는것이 중요한 것 같다.