AI와 며칠씩 같은 프로젝트를 개발하다 보면 어느 순간 대화 자체가 프로젝트 관리 도구가 된다.
“아까 말했던 그 기능”, “저번에 수정한 규칙”, “이전 채팅에서 정했던 예외”가 계속 쌓인다. 초반에는 편하지만, 대화가 길어질수록 무엇이 최신 결정인지 찾기 어려워졌다.
그래서 큰 작업은 별도의 Task MD를 만들고, 그 파일을 source of truth로 사용하기 시작했다.
대화는 의사결정 과정이고 문서는 현재 상태다
채팅에는 아이디어, 취소된 제안, 중간 수정, 오해, 정정이 모두 남는다.
예를 들어 처음에는 A 방식으로 만들자고 했다가 실제 구현 중 B 방식이 낫다고 판단해 바꿀 수 있다. 대화만 읽는 agent는 앞의 A와 뒤의 B를 모두 보게 된다.
Task MD에는 최종적으로 살아남은 B만 남긴다.
이렇게 역할을 분리하니 “우리가 전에 뭐라고 했지?”보다 “현재 task 문서가 뭐라고 정의하고 있지?”를 먼저 볼 수 있게 됐다.
큰 작업만 별도 문서로 관리했다
모든 수정마다 문서를 만들면 오히려 관리비용이 커진다.
그래서 다음 같은 작업만 별도의 task 파일로 관리했다.
- 여러 파일을 수정하는 작업
- 데이터 구조가 바뀌는 작업
- 로그인·권한·보안처럼 위험도가 높은 작업
- 여러 단계로 나눠야 하는 기능
- 완료 기준을 명확히 적어야 하는 작업
작은 문구 수정이나 단순 CSS 변경까지 같은 절차를 강제하지 않았다.
완료 조건을 코드보다 먼저 적었다
Task MD에서 가장 도움이 된 부분은 “무엇을 만들지”보다 “어떻게 끝났다고 판단할지”였다.
예를 들면 다음 항목을 먼저 적는다.
- 사용자가 실제로 보게 될 결과
- 변경해야 하는 영역
- 건드리면 안 되는 영역
- 테스트 항목
- 운영 반영 전에 확인할 것
이 내용이 있으면 agent가 구현을 마친 뒤 스스로 작성한 코드를 기준으로 성공을 주장하는 일을 줄일 수 있다. 성공 기준이 코드 밖에 존재하기 때문이다.
다음 agent에게 전체 과거 대화를 넘기지 않아도 됐다
모델이나 coding agent를 바꿀 때 가장 큰 문제는 컨텍스트였다.
기존 대화를 통째로 붙이면 토큰도 많이 들고, 이미 폐기된 아이디어까지 같이 전달된다. 반대로 너무 짧게 요약하면 중요한 제약을 빼먹기 쉽다.
Task MD를 최신 상태로 유지하면 새 agent는 문서와 현재 저장소를 읽고 바로 시작할 수 있다.
GitHub 저장소가 단순한 코드 보관소가 아니라 사람과 agent 사이의 durable handoff 지점이 되는 셈이다.
문서를 다시 쓰는 것보다 현재 파일을 읽는 것이 중요했다
여기서 또 하나의 규칙을 만들었다.
이미 task 파일이 있다면 과거 대화나 기억을 바탕으로 새 문서를 재작성하지 않는다. 반드시 현재 저장소의 실제 파일을 먼저 읽고 수정한다.
작은 표현 하나가 빠지는 것보다 더 위험한 건, 예전 상태를 최신이라고 믿고 문서를 덮어쓰는 것이었다.
문서의 목적은 완벽한 기획서가 아니다
Task MD를 쓰기 시작했다고 해서 개발 전에 긴 PRD를 만드는 방식으로 돌아간 것은 아니다.
목적은 훨씬 단순했다.
다음 작업자가 현재의 결정과 경계를 빠르게 이해하게 만드는 것.
AI와 개발할수록 문서가 많아져야 하는 게 아니라, 무엇이 현재 사실인지 가리키는 기준점이 더 중요해졌다.