AI를 위한 인수인계 문서를 만들었다

[한줄 요약]
AI는 새 세션마다 많은 기억을 잃는다.
그것을 막기 위한 MD파일 구조를 체계화하여 효율적인 인수인계 방식을 만들었다.

[개요]
에이전트 개발의 가장 큰 병목은 역시 '세션'의 한계라고 생각합니다. 세션에는 컨텍스트 용량 문제가 있기 때문에, 언젠가 반드시 세션을 마무리하고 새로운 세션을 생성해야하는 상황이 옵니다. ( /compact를 쓰면되지 않냐고 하실 수도 있는데, 몇 번까지는 가능해도 영원히 축약시킬 수는 없다고 봅니다. 빠르냐 늦냐의 문제이고 결국 언젠가는 세션을 마무리해야할 때가 온다고 봅니다.) 그렇게 새 세션으로 가면 늘 귀찮은 문제가 있습니다. 이전까지의 컨텍스트에 들어 있던 AI의 기억들. 나와 대화하며 만들어진 세세한 디테일들이 사라진다는 것입니다. 파일 구조나 코드는 전부 그대로입니다. 하지만 새로 온 AI는 그것을 처음 보기 때문에 처음부터 전부 다시 파악하는 과정을 거치게 됩니다. 이것은 사람으로 치면 1~3일 마다 같은 업무를 다른 사람이 처음부터 배워서 시작하는 것과 같습니다. 물론 사람이 아닌 AI기 때문에 그 과정은 크게 오래 걸리지 않으며 그리 비효율적으로 보이지도 않습니다. 하지만 매번 전체 파악을 처음부터 해야한다면 내부적으로 다소의 지연이 알게 모르게 생기고 있는 것이고, 토큰 사용량도 조금씩 낭비될 가능성이 있습니다. 그러면 어떤 해결법이 있을까요?

1. MD파일

MD(Markdown) 파일은 문서 형식의 파일입니다.(기호로 서식을 넣는.)
기호를 통해 표와 코드 등을 표현할 수도 있습니다. 개발자가 애용하는 형식 중 하나입니다.

여기저기 호환성이 좋다. (Github와도 연동되고 각종 에디터 등)
단순하며 간편하다. (마우스 없이 작성이 가능하고 오류가 딱히 없음)
AI가 이해하기 좋은 형식이다.

MD파일은 AI에게 줄 텍스트 문서로 가장 적절한 형식 중 하나라고 볼 수 있습니다. 실제로 많은 개발자들이 AI에게 지침이나 규칙을 줄 때 MD파일을 자주 씁니다.

다르게 표현하면...

MD파일은 프롬프트를 입력하기도 전에 미리 주입시키는 프롬프트다

라고 쉽게 표현할 수 있을 것 같습니다. (정확한 표현인지는 모르겠습니다.)
어차피 매번 입력해야한다면 아예 기본설정으로 입력되도록 한다. 라는 것이 MD파일 한개로 구현하는 기본 지침서입니다. 'AGENTS.MD', 'CLAUDE.MD'를 대표적인 예시로 들 수 있습니다.

그럼 MD파일만 쓰면 완벽한가? 라고 하신다면 그것은 아닙니다. 왜냐면, MD파일에는 한계가 있습니다. 통상적으로 200줄 이상을 넘으면 컨텍스트에 부담이 된다고 알려져 있습니다. 제한된 환경 내에서 효율적인 서술이 필요합니다. 하지만 아무리 정제하고 다듬어도 여러 프로젝트에 대한 내용을 전부 넣기에는 역부족입니다. 이러한 제약을 겪다보면, 자연스레 아래 2번의 발상으로 연결됩니다.

2. 여러개의 MD파일

하나의 MD에는 제한이 있다. 따라서 여러개의 MD를 만든다.

아주 간단한 발상이면서도 효과적이며, 표준 방식에 가깝다고 봅니다.
1번의 MD파일이 모여서 구조를 이루도록 설계하면 이것이라고 봐도 될 것 같습니다.
그럼 MD 여러개를 쓰기만 하면 완벽한가? 라고 하신다면 그것도 아닙니다.
MD여러개를 툭 던져놓으면, AI가 그것을 필요에따라 적절히 읽을 것이라는 보장이 불가능합니다. A에 대한 내용을 진행하는데 B에 대한 MD파일만 읽을 수도 있다는 것이죠. 이것은 자연스레 아래 3번의 발상으로 연결됩니다.

3. 구조화된 MD파일

그렇다면 이런 것이 가능하다면 어떨까요?

AI가 반드시 읽는 하나의 설명서가 있어서, 그곳에는 다른 모든 MD파일로 가는 길이 적혀있다.

이것이 제가 만든 Dear-Agents입니다. 다른 모든 MD파일로의 연결점이 되어주는 CLAUDE.md(AGENTS.MD)를 통해 다른 핵심 MD들에 접근할 수 있도록 했습니다.

PLAN.md - 프로젝트의 전체적인 큰 계획 기록
HANDOFF.md - 최근 진행중인 작업과 현황 기록
LOG.md - 개발 진행된 내역 기록
README.md - 사용법
CLAUDE.md - 다른 모든 MD파일로의 연결점이 되어줌.

이런 식으로 응용해서 MD를 늘려도 문제 없이 기능합니다.
적극적으로 필요한 MD파일을 늘리는 것이 좋다고 봅니다.
제가 만든 구조는 비교적 단순합니다. 어느정도 기능을 하는 단위를 만들기 위해 최소한으로 구현한 것에 가깝습니다. 단, 스킬 등록도 자동으로 되도록 설정해놓았기 때문에 조금 더 편할 것 같습니다. 프로젝트의 구조 형성에 어려움을 겪는 분들에게는 도움이 될만하다고 생각합니다. 자세한 내용은 깃허브의 해당 페이지에도 있으니 참고 부탁드립니다. 감사합니다.

1. MD파일

2. 여러개의 MD파일

3. 구조화된 MD파일

댓글