Git은 코드만 보존한다. 교훈은 누가 보존하는가?

커밋(commit)은 도움말 버튼이 언제 나타났는지 알려줄 수 있습니다. 하지만 게임을 만들던 사람이 어떻게 플레이해야 할지 전혀 모른다고 말했을 때, 이미 자동화된 검사를 통과했다는 사실까지는 보통 알려주지 못합니다.

이는 제가 Claude Code와 함께 작업하던 과정에서 일어난 일이었습니다.

프로젝트는 Three.js와 Blender 에셋을 사용해 만든 브라우저 게임인 BUTTERFLY JOB이었습니다. 플레이어는 과거를 바꿔 현재에 은행 강도를 가능하게 만듭니다. 세션 기록에는 성공적인 브라우저 및 유닛 검사가 포함되어 있었습니다. 그러다가 +3시간 43분 경, 제가 무엇을 해야 할지 파악할 수 없어 개입했습니다.

그 결과 에이전트가 사용법 대화창(how-to dialog), 영구 가이드, 그리고 도움말 버튼을 추가했습니다.

이러한 변경 사항들은 Git에 기록되어야 합니다. 그 이유 역시 마찬가지입니다. 하지만 누군가가 의도적으로 그 이유를 문서로 남기지 않는 한, 다음 개발자는 UI 변경 사항만 보고 '테스트된 경로를 가진 게임이 새로운 플레이어가 그 경로를 발견할 수 있다는 것을 의미하지는 않는다'는 교훈을 스스로 재구성해야 합니다.

저는 코딩 에이전트와 작업하는 이 부분을 보존하기 위해 Coders Talk를 만들었습니다.

수정 사항과 그에 대한 응답은 public Build에 함께 보존되어 있습니다.

diff만으로는 설명의 일부일 뿐입니다

Git은 우리가 커밋하는 변경 사항을 보존합니다. 좋은 커밋 메시지, 풀 리퀘스트(pull request), 또는 결정 기록이 그 추론 과정까지도 보존할 수 있습니다. 저는 이 모든 것을 여전히 원합니다.

하지만 최종 변경 사항이 커밋으로 들어가기 전에도 많은 일이 일어납니다.

당신은 에이전트에게 무언가를 구현하도록 요청합니다. 첫 번째 해석은 그럴듯하지만, 제약 조건 하나를 놓칩니다. 당신이 그것을 수정합니다. 에이전트는 다른 접근 방식을 시도합니다. 테스트가 잘못된 가정을 드러냅니다. 당신은 초기 프롬프트에 포함되었어야 할 세부 사항을 추가합니다.

작업이 완성될 무렵에는 코드가 그럴듯하게 보입니다. 버려진 접근 방식은 사라졌을 수도 있습니다. 유용한 수정 사항은 긴 대화 속 어딘가, 명령어 출력과 또 다른 테스트 실행 사이에 놓여 있을 수 있습니다.

2주 후에, 당신은 비슷한 것을 해결했던 기억이 납니다. 하지만 에이전트의 방향을 바꾼 문장 자체는 기억나지 않습니다.

원시 로그(raw log)를 보존하는 것이 도움이 됩니다. 관련 턴(turn)을 찾고, 그것에 앞선 내용을 이해하며, 이것이 오늘 작업에 적용되는지 결정하는 것 역시 여전히 노력이 필요합니다.

제가 Coders Talk로 채우고 싶었던 바로 그 간극입니다. 저는 세션으로 돌아와 다음과 같은 질문에 답하고 싶었습니다. 과제는 무엇이었는지, 접근 방식은 어디서 실패했는지, 그리고 인간이 개입한 후에 무엇이 바뀌었는지 말입니다.

세션이 빌드(Build)가 되다

Coders Talk에서 **빌드(Build)**란 작동하던 세션을 핵심 순간들로 압축한 것이며, 그 밑바탕 기록은 저자가 공유할 수준에 따라 이용 가능합니다.

format에는 목표, 타임라인, 결과, 그리고 다음번에 다르게 할 수 있는 것(verdict)이 있습니다. 이 타임라인은 다섯 가지 종류의 순간을 사용합니다:

제가 가장 중요하게 생각하는 부분은 개입(intervention)에 붙는 '왜(why)' 입니다. “저는 에이전트를 멈췄습니다”라는 말은 다른 개발자에게 매우 적은 정보를 제공합니다. “테스트가 경로를 커버했지만, 첫 번째 액션을 발견할 수 없었습니다”라는 말은 그들 자신의 프로젝트에서 확인할 무언가를 제공합니다.

BUTTERFLY JOB 세션에서는 초기 수정 덕분에 자산 요구 사항이 명확해졌습니다. 즉, 보이는 모든 3D 객체는 Blender에서 작성되어 브라우저용으로 내보내져야 한다는 것이었습니다. 그러자 에이전트는 계속 진행하기 전에 대표적인 자산(representative asset)을 사용하여 그 파이프라인을 검증했습니다.

동일한 빌드(Build)는 두 가지 종류의 개입 사항을 모두 보존합니다. 즉, 초반에 명확해진 제약 조건과 후반에 발견된 사용성 문제가 그것입니다. 이는 단순히 에이전트가 결국 플레이 가능한 게임을 만들었다는 사실만 기억하는 것보다 훨씬 유용합니다.

작동 방식

플러그인을 설치하면 작업 중인 세션을 전송할 수 있습니다:

Claude Code: /coders-talk: build
Codex:       $coders-talk:build

수동으로 전송할 경우, 플러그인이 무엇을 업로드하고 초안이 어디에 들어갈지 보여줍니다. 이 과정에서 부피가 큰 세션 자료는 제거되고, 감지된 비밀 정보(secrets)는 로컬에서 마스킹 처리되며, 준비된 세션을 전송합니다. 서버에서도 이를 다시 확인합니다.

모델은 제목, 주요 순간(moments), 그리고 초안 판정(draft verdict)을 제안합니다. 사용자는 이러한 제안들을 편집하고, 수정의 이유를 설명하며, 요약이 무슨 일이 일어났는지 정확히 기술하는지 확인해 나갈 수 있습니다. 이 페이지는 모델의 기여도를 식별해주며, 세션을 요약한다고 해서 그 요약이 오류가 없다는 것을 의미하지는 않습니다.

결과는 비공개 초안(private draft)으로 시작하거나, 해당 세션이 속한 저장소 중 하나에 속할 경우 팀 공간으로 이동합니다. 전송한다고 해서 자동으로 공개되는 것은 아닙니다. 자동 모드(Auto mode)는 선택 사항이며 별도로 활성화해야 합니다.

짧은 읽기 자료 뒤에는 맥락이 존재합니다: 즉, 에이전트와 모델, 세션 지속 시간, 개입 사항들, 그리고 기록된 경우 토큰 사용량, 코드 변경 사항, 커밋 등이 포함됩니다. 이러한 맥락은 다른 사람의 경험이 자신의 작업에 관련성이 있는지 판단하는 데 도움을 줍니다. 성공적인 실행 한 번만으로는 보편적인 레시피가 되는 것은 아닙니다.

작업물을 반드시 공개할 필요는 없습니다

만약 유용한 세션이 비공개 저장소에서 발생한다면, 여전히 그 교훈들을 보존할 수 있어야 합니다.

Coders Talk에서는 해당 기록을 세 가지 방식으로 사용할 수 있습니다. 자신만을 위해 보관하거나, 팀 내부에서 사용하거나, 다른 사람들이 배울 수 있도록 빌드(Build)를 공개할 수 있습니다. 공개 공유는 선택 사항입니다.

개인에게 있어 즉각적인 가치는 전체 대화를 다시 읽지 않고도 이전의 수정 사항을 찾는 것입니다. 팀에게 있어서는 반복되는 문제가 팀원들이 에이전트(agents)에게 전달되기 전에 검토해야 할 제안된 규칙(proposed rule)이 될 수 있습니다. 팀 워크플로우를 통해 이 규칙은 이를 설명하는 세션과 연결됩니다.

빌드를 공개할 때, 노출 범위를 선택합니다: 요약본(summary), 선택된 발췌문(selected excerpts), 또는 전체 세션입니다. 모든 대화를 노출하지 않고도 교훈을 유용하게 활용할 수 있습니다.

'비공개(Private)'는 누가 빌드에 접근할 수 있는지를 설명합니다. 준비된 세션은 여전히 서버에 업로드되고 처리됩니다. 플러그인은 환경(environment) 및 키 파일(key-file) 내용을 숨기고 감지된 비밀 정보(secrets)를 마스킹하여 업로드하지만, 공개하려는 모든 내용은 사용자가 직접 검토해야 합니다. 플러그인 문서에서 무엇이 전송되는지 설명합니다.

교훈은 다음 세션에 도달해야 한다

기록은 다음에 무엇을 할지 변화시킬 때 더 유용해집니다.

빌드(Build)에는 **플레이북(Playbook)**이 있을 수 있습니다. 이는 해당 세션에서 얻은 접근 방식, 함정(pitfalls), 그리고 검토 항목들입니다. 페이지에서는 조언 뒤에 숨겨진 순간들을 확인할 수 있습니다. **'이 빌드 사용하기(Use this Build)'**를 통해 이를 프롬프트(prompt), 스킬(skill), 또는 CLAUDE.md나 AGENTS.md의 저장소 규칙으로 재사용할 수 있습니다. 플레이북 작동 방식은 여기에서 확인할 수 있습니다.

BUTTERFLY JOB의 경우, 플레이북은 초보자가 첫 번째 행동을 찾을 수 있는지 확인해야 할 필요성을 전달합니다. 이는 해당 조언이 촉발된 개입(intervention)과 다시 연결됩니다.

[

제공된 조언은 자동화된 검사가 불충분했던 순간을 포함하여, 확인할 수 있는 출처가 있습니다.

사용자의 에이전트는 Coders Talk MCP 서버를 통해 게시된 빌드(Builds)를 검색할 수도 있습니다. 이를 통해 유사한 작업이나 이전에 발생했던 실패 기록을 시작하기 전 또는 막혔을 때 찾아볼 수 있습니다.

이는 다음 세션에 더 구체적인 시작점을 제공합니다. 단순히 “철저히 테스트하라”는 모호한 지시 대신, 이전 세션에서 놓친 검사를 요청할 수 있게 됩니다. 물론 이 내용이 프로젝트에 적합한지는 사용자가 결정해야 합니다.

하나의 교정 사항 유지하기

가장 쉽게 시작할 수 있는 곳은 무언가를 두 번 설명해야 했던 세션입니다.

마침내 도움이 되었던 교정 사항을 찾아보세요. 그 주변의 맥락을 함께 보존하세요. 다음에 첫 번째 프롬프트에 무엇을 넣을지 적어두세요.

이것은 오늘 Markdown 파일에서 할 수 있습니다. 저는 Coders Talk를 구축하여, 이 메모 뒤에 있는 세션을 보존하고, 다시 찾고, 그 교훈을 다른 실행으로 가져가기 쉽게 만들었습니다.

직접 사용해 보고 싶다면, 하나의 세션을 비공개 빌드(private Build)로 전환해 보세요. 나중에 공유할 가치가 있는지 결정해도 됩니다.

코딩 에이전트에게 계속 제공하고 싶지만, 처음부터 저장하지 못했다고 생각하는 교정 사항은 무엇인가요?