AI가 MD 파일로 작업 흐름을 기록하게 한 이유

왜 이렇게 쓰게 되었나?

처음에는 AI가 “코드를 대신 다 써 준다”라는 안일한 생각을 했다. 필요한 기능을 작성하면 빠르면서도 깔끔하게 웹 페이지 초안이 나왔다.

역시 “바이브 코딩이 대세구나”라고 생각했다. 그러나 코드가 길어질수록 프로젝트에서 AI가 얼마나 정확하게 목표를 짚고 작동하는지가 더 중요해졌다.

AI를 이용해 코딩하다 보면 새 대화를 열거나 며칠 뒤에 돌아올 때마다 목표·진행·결정 이유를 처음부터 다시 늘어놓게 된다. 도구가 이전 내용을 기억하더라도 요약된 맥락에 의존하는 경우가 많아, 원래 의도와 다르게 해석되는 일이 있었다.

긴 스레드 안에서는 말이 금방 묻히고, 어디까지 왔는지도 흐릿해진다. 대화창에만 기대면 작업 흐름이 잘 끊긴다고 느꼈다.

그래서 작업 중에 AI가 Markdown 파일을 읽고, 한 덩어리가 끝날 때쯤에는 상태를 갱신해 두는 방식으로 바꿔 보았다.

사람이 개발 일지처럼 매 줄을 적는 느낌이 아니라, AI가 작업 계획과 우선순위를 정리하고 현재 진행 상황을 체크리스트처럼 갱신하는 방식이다.

이렇게 하니 나도 작업 상황을 공유받을 수 있었고 작업 계획을 수정하기도 편해졌으며 이전의 결과 요약을 확인하기도 수월했다.

내가 써 본 폴더 구조

이 구조가 그렇게 좋은 구조인지는 모르겠다. 그러나 시도하고 사용한 입장에서 간단히 정리해봤다.

AGENTS.md는 프로젝트 루트에 둔다.(_private/ 밖이다.) 작업 전에 반드시 지켜야 할 규칙이라, 공개해 두는 코드와 같은 층에 두는 편이 낫다고 판단했다.

CONTEXT.md, reports/, plans/, logs/, rules/, archive/는 _private/ 아래에만 둔다.

_private/은 공개 GitHub 저장소에는 올리지 않을 내부 작업 기록을 한곳에 모아 둔 폴더이다. .gitignore로 해당 디렉터리만 빼 두면 작업 과정이 담긴 파일을 로컬에서만 사용할 수 있다.

project/
  AGENTS.md
  _private/
    CONTEXT.md
    reports/
    plans/
    logs/
    rules/
    archive/

• AGENTS.md (루트): 작업 시작 전에 봐야 할 최상위 규칙
• _private/CONTEXT.md: 지금 상태를 빨리 훑는 요약
• _private/reports/: 분석·이슈·방향·우선순위
• _private/plans/: 순서, 기준, 검증, 남은 일
• _private/logs/: 세션별로 무슨 일이 있었는지, 다음에 뭘 할지
• _private/rules/: 자주 되짚게 되는 세부 규칙
• _private/archive/: 당장 손대진 않지만 나중에 찾을 수 있는 과거 기록

_private/CONTEXT.md나 _private/plans/를 먼저 읽히면, 이전에 무슨 일을 하고 있었는지 이어 붙이기가 분명히 쉬웠다. 한 작업이 끝난 뒤에 AI가 _private/plans/나 _private/logs/를 갱신해 두면, 진행 상황을 확인하고 이어나가기 더 편리했다. 특히 이전에 했던 작업들을 모아서 보고싶을 때 유용했다.

AGENTS.md는 루트의 뼈대 규칙이고, _private/rules/는 상황마다 다시 읽게 되는 디테일에 가깝다.

내가 신경 쓴 건 사람이 모든 문장을 직접 적는 그림이 아니라, AI가 읽고 쓰는 상태 문서에 가깝게 두는 쪽이었다. 사람은 흐름이 궁금할 때 파일을 열어 보고, 틀렸거나 낡은 부분만 골라서 고치거나, “여기부터 다시 정리해 줘”라고 넘기면 된다.

실제로 체감한 점

AI 작업을 껐다 다시 시작해도 작업의 줄기가 통째로 사라지지 않는다는 점이 가장 좋았다.

예전에는 새 채팅마다 “우리가 뭐 하고 있었지?”를 다시 써야 했다. AGENTS.md와 _private/CONTEXT.md, _private/plans/ 같은 파일을 먼저 읽히게만 해도, 체감상 이어 가기가 훨씬 수월했다.

기록이 없을 때는 중간에 방향이 흐트러지는 경우가 잦았는데, 지금은 그 빈도가 줄었다. 토큰 한도나 세션이 갑자기 끊겨도, 디스크에 남아 있는 쪽이 좋았다.

“왜 이렇게 했는지”가 남아 있으면, 나중에 다시 판단할 때도 덜 막막했다.

맥락을 채팅에만 두지 않기

중요한 정보를 대화창 안에만 두면 작업이 끊기기 쉽다.

로컬 프로젝트 안의 Markdown이 있으니 AI가 끊긴 작업을 계속 이어나갈 수 있었다. 별도 뷰어도 없이 에디터로 바로 열 수 있고, 이어나간 작업을 까먹었을 때 볼 수 있어 요청사항을 입력하기 수월했다.

예: widget24.app 프로젝트

widget24.app 같은 프로젝트에서는 특히 그랬다.
기존에 AI의 도움을 받아 만든 코드를 유지보수하고 기능을 추가하는 프로젝트였다.

디자인을 수정하거나 기능을 추가하거나 리팩터링을 할 때, 종종 디자인이 달라지는 일이 있었다.
요구하지 않은 요소가 추가되는 경우도 있었다.

그래서 “이 기능만” 한 줄로 던지기보다, _private/ 폴더의 Markdown 파일에 목표·규칙·남은 일이 적혀 있을 때 결과가 더 고르다고 느꼈다.

더 생각해볼 점

Markdown을 썼다고 모든 게 풀리는 건 아니다. 기록이 쌓이면 오래된 문단이 그대로 남기 쉽고, AI가 그걸 현재라고 읽을 수도 있다.

AI가 기록하는 과정에서도 토큰 소모가 늘어난다는 단점도 있다.

그래서 “많이 적었다”보다 최근에도 사실인 상태인가를 같이 맞춰 가는 쪽이 더 중요하다고 본다. 사람이 가끔 열어서 틀린 줄을 지우고, 필요하면 AI에게 “요약만 다시 잡아 줘”라고 부탁하는 식이다.

폴더 구조도 갈수록 최대한 줄여가며 필요한 것만 남기는 것이 좋을 듯하다.

정리

코드를 대신 써 주는 도구만으로는 부족하고, 지금 무슨 일을 하고 있는지가 같이 따라와야 한다.

나는 그걸 Markdown에 읽히고 갱신되게 두는 방향으로 개선했다.

정답이라기보다, 그렇게 써 보니 덜 끊기고 덜 말로 설명하게 된다는 일종의 경험을 공유한 것이라고 보면 좋겠다.