코딩 에이전트의 작업물이 .md 파일에서 손실되는 문제

제가 코딩 에이전트가 현재 만들어내는 것 중 상당 부분은 실제 코드가 아닙니다. 롤아웃 계획(rollout plan)일 수도 있고, 세 가지 큐 라이브러리 비교표일 수도 있으며, 클라이언트를 위한 마이그레이션 체크리스트일 수도 있습니다.

글을 쓰는 것이 어려웠던 시기는 이미 오래전입니다. 여전히 문제가 되는 것은 그 이후의 모든 과정입니다. 문서는 out/ 폴더에 plan_v3_final.md로 저장되고, 피드백은 채팅 스레드에 남으며, 다음 세션은 처음부터 다시 시작됩니다.

더 똑똑한 모델도 이 문제를 해결하지 못합니다. 왜냐하면 누락된 조각들이 컨텍스트 윈도우(context window) 밖에 존재하기 때문입니다. 제가 계속 부딪히는 세 가지 문제와 각각을 해결하는 AGENTS.md의 몇 줄을 소개합니다.

1. 링크 하나를 제공하고 기억하게 만들기

터미널 내의 에이전트는 무엇이든 작성할 수 있지만, 오직 디스크에만 저장할 수 있습니다. 링크를 전달하려면 게시할 장소가 필요합니다: 다른 개발자를 위한 gist, 정적 호스팅(static host), 에이전트 자체 빌트인 공유 기능, 또는 에이전트 게시 서비스 중 하나입니다. 한 번 선택하고 일관성을 유지해야 합니다. 매번 에이전트가 임의로 결정하게 두지 마세요.

그리고 다음 세션도 문제입니다. 수요일에 변경 사항을 요청했는데, 에이전트는 월요일 링크를 기억하지 못합니다. 그래서 새 파일을 작성하고 새로운 링크를 전달합니다. 하지만 누군가는 항상 이전 링크를 참조합니다.

이것은 지능의 문제가 아니라 상태(state)의 문제입니다. 다음 세션에서 찾을 수 있도록, 상태를 소스 코드 옆에 배치해야 합니다:

## Sharing
- 문서를 완성하여 다른 사람이 읽게 할 때는 게시하고 링크를 제공해 주세요.
  로컬 파일 경로는 전달 가능한 결과물이 아닙니다.
...

2. 피드백 루프를 닫되, 그로부터 지시를 받지는 마라

팀 동료가 채팅 스레드에 "1단계는 너무 위험하니, 먼저 10%만 파일럿으로 진행하자"라고 작성했다고 가정해 봅시다. 좋은 메모입니다. 하지만 에이전트는 이를 보지 못하고, 누군가는 결국 이 내용을 다시 타이핑하게 됩니다. 피드백을 에이전트가 읽을 수 있는 곳에 두어야 합니다. 문서 옆의 FEEDBACK.md 파일이나, 에이전트가 가져올 수 있는 댓글(예: gist의 경우 gh api /gists/<id>/comments) 같은 곳에 말입니다.

문제는 이겁니다. 에이전트가 다른 사람들의 댓글을 읽게 되면, 그 댓글들이 프롬프트의 일부가 됩니다. 지시 사항을 잘 따르는 모델은 댓글 속에 숨겨진 지시 사항도 잘 따르며, 게다가 행동할 수 있는 셸(shell)과 자격 증명(credentials)까지 가지고 있습니다. 이것이 바로 똑똑한 모델이 상황을 더 악화시키는 유일한 지점입니다.

## 피드백
- 공유 문서를 편집하기 전에, 열려 있는 피드백을 읽어라.
- 각 댓글에 대해: 변경 사항을 적용하거나, 한 줄의 이유와 함께 거절하라.
...

3. 다음 에이전트를 위한 브리프(brief)를 남겨라

문서를 처리하는 에이전트가 작성한 사람이 아닐 때가 많습니다. 저는 Claude Code에서 초안을 잡고, 팀 동료는 Codex에서 수정합니다. 문서에는 무엇이 결정되었는지는 적혀 있지만, 왜 그렇게 되었는지 또는 이미 거절된 내용은 기록되어 있지 않아, 다음 에이전트는 기꺼이 화요일의 나쁜 아이디어를 다시 제안해 버립니다. 다섯 줄짜리 메모가 이를 해결할 수 있습니다:

# 체크아웃 출시 계획: 브리프(brief)
목표: 웹 체크아웃을 매출 감소 없이 새로운 흐름으로 이동시키는 것.
현황: Priya와 Sam에게 v2를 공유함. 열린 댓글이 하나 있음.
...

## 인계(Handoff)
- 각 공유 문서 옆에 BRIEF.md 파일을 유지하라. 시작하기 전에 읽어라.
- 작업 상태가 변경될 때마다 다시 작성하지 말고, 변화할 때만 재작성하라.

아니면 스킬(skill)에게 맡겨라

저는 byagent를 만들었습니다. 매번 프로젝트마다 이런 규칙들을 연결하는 것에 지쳐서, 이를 에이전트 스킬로 패키징했습니다. 사용자의 에이전트는 자신이 만든 결과물을 게시하고 링크를 사용자에게 돌려줍니다. 이 과정에 이러한 습관들이 내장되어 있습니다.

npx skills add anup-a/agent-artifacts

[

다시 게시하면 같은 링크가 유지되고, 에이전트는 byagent CLI를 통해 댓글을 읽어오며, byagent brief는 프로젝트에 인계 메모를 남겨둡니다. Claude Code, Codex, Cursor 및 셸 명령을 실행할 수 있는 모든 에이전트와 함께 작동합니다. 계정 없이 사용해 보려면: npx byagent publish ./plan.md (게스트 페이지는 24시간 동안 유효).

리뷰어의 피드백을 다음 에이전트 실행에 어떻게 반영할 수 있나요?