AI 에이전트를 위한 문서 구조
프로젝트 준비를 위해 대화했던 ChatGPT와 Gemini는 AI 챗봇이었다. 내가 질문이나 지시를 내리면 그에 대한 답변을 준다. 그리고 단순히 질문에 답하는 데서 나아가, 목표를 주고 개발 작업을 이어가도록 맡기면 그것이 곧 AI 에이전트였다.
AI 에이전트가 개발 작업을 일관성 있게 진행해 나가려면 정확히 무엇을 만들어야 할지, 어떤 결정이 최신인지, 작업 절차와 규칙은 무엇인지 등이 문서에 명확하게 정리되어 있어야 한다. GitHub를 사용하기로 했으니, 다음 단계는 그동안 AI와 대화하며 다듬은 제품 아이디어와 요구사항을 정리하여 저장소로 옮기는 일이었다. 처음에는 내가 직접 대화들을 수동으로 병합하고 제품 명세를 작성해보려고 했으나 내용이 중복되거나 불필요해진 것도 많아서 여간 번거로운 일이 아니었다. 가만 생각해보니 이런 작업이야말로 AI가 가장 잘하는 일이 아니던가? 아무 생각 없이 Microsoft Word로 작성하고 있던 문서를 AI 에이전트가 읽고 쓰기 편한 Markdown 형식으로 바꿨다. 그 동안의 대화들을 모두 Markdown 파일로 저장해달라고 해서 다운받은 다음 ChatGPT에게 모든 대화 파일들이 담겨있는 폴더를 주고 AI가 프로젝트를 진행하기 좋은 구조를 제안해달라고 했다. 대화 요약은 참조용으로 보존하고, 결정 기록에 무엇을 선택했는지 쌓아가고, 현재 상태 문서에 지금 따라야 할 기준을 담는 방향으로 아래와 같이 구성해주었다.
/
README.md
AGENTS.md
archive/
sessions/
2026-06-09-mvp-discussion.md
2026-06-10-cost-analysis.md
2026-06-11-chat-distillation-plan.md
docs/
00-current-state.md
01-decision-log.md
02-open-questions.md
03-conflicts-and-reconciliation.md
04-project-journal.md
05-glossary.md
architecture/
overview.md
data-model.md
adr/
ADR-0001-project-name.md
ADR-0002-mvp-foundation.md
agent-prompts/
conversation-distillation-prompt.md
doc-update-prompt.md
adr-generation-prompt.md
research/
competitors.md
technical-options.md
storage-cost-model.mdREADME.md는 사람과 AI 에이전트 모두를 위해 프로젝트가 무엇인지, 현재 어디까지 결정되었는지, 어디를 먼저 읽어야 하는지를 알려주는 역할. AGENTS.md는 AI 에이전트에게 주는 운용 규칙. ADR은 Architecture Decision Record의 약자로 주요 설계 결정 사항을 기록하는 용도.
이제 작업을 맡기면 AI 에이전트가 docs 폴더에 있는 문서들을 읽고 프로젝트를 파악할 수 있게 되었다. AI 에이전트가 한 번에 읽고 기억할 수 있는 문서의 양은 제한되어 있기 때문에 (컨텍스트 길이) 꼭 필요한 문서만 읽도록 신경 써야 했다. 프로젝트 브레인스토밍을 위해 나누었던 과거 대화는 요약본으로 archive에 보관해두고 명시적으로 요청할 때만 참고하도록 AGENTS.md, .aiignore, .cursorignore와 같은 AI를 위한 작업 규칙에 적어두었다.
문서 구조가 확정되면서 더 이상 AI와 프로젝트에 대해 상의할 때 필요한 배경과 맥락을 매번 다시 입력해주지 않아도 되었다. AI에게 GitHub 저장소를 읽을 수 있는 권한을 주고 해당 프로젝트에 대한 대화라는 것만 알려주면 언제든 저장소에 정리된 상태를 바탕으로 대화할 수 있었다. 단, 저장소 문서를 항상 최신으로 유지하는 것은 별개의 문제였다. 프로젝트가 진행되고 규모가 커가면서 문서 관리를 위해 개선할 점들이 생겨나는데 이는 추후 별도의 글로 다루어볼 예정이다.