EP 04

context.md는 계속 진화한다


2026년 5월·4 min read·#documentation#architecture#logging

오늘 코드를 한 줄도 짜지 않았다.

그런데 페퍼가 많이 바뀌었다.


문서가 시스템이다

context.md는 한 번 만들면 고정되는 게 아니었다. 생각이 바뀌면 문서가 먼저 바뀌고, 문서가 바뀐 다음에 Claude Code를 부른다. 이 순서가 중요하다. 반대로 하면 코드가 꼬인다.

오늘만 버전이 0.4.0에서 0.9.0이 됐다. 하루에 다섯 번 올라갔다.


가장 무서운 건 에러가 나는 게 아니다

며칠 전 일이다. 리포팅 기능을 고치다가 다른 곳이 이상해졌다. 뭘 건드렸는지 몰랐다. 어디서 망가진 건지도 몰랐다. 그냥 "뭔가 안 된다"는 것만 알았다.

비개발자의 가장 큰 취약점이 이거다. 에러가 나도 어디서 왜 났는지 읽지 못한다. 지엽적으로 하나를 고쳤는데 연결된 다른 곳이 조용히 깨진다. 그게 쌓이면 어느 순간 전체가 꼬여있다.

그래서 에러가 났는데 모르는 것이 진짜 두려움이었다. 에러 자체보다.


pepper_logs — 페퍼의 블랙박스

오늘 이 문제를 정면으로 다뤘다.

pepper_logs
. 페퍼가 한 모든 행동의 단일 관찰 지점이다. 사용자 요청이든, 백그라운드 워커든, LLM 호출이든 — 전부 하나의 테이블에 쌓인다.

뭘 요청했나. 됐나 안 됐나. 안 됐으면 왜 안 됐나. STATE B에서 코드 생성이 실패했다면 1~3번 시도 전부와 에러 메시지까지.

나중에 페퍼가 이상하게 동작할 때 Claude Code한테 이렇게 말할 수 있다.

"pepper_logs에서 오늘 에러 찾아줘."

그게 전부다. 내가 에러를 읽지 못해도 된다. 로그가 있으면 Claude Code가 읽는다. 로그가 없으면 — 둘 다 모른다.

비행기 추락 원인을 블랙박스 없이 밝히는 것과 같다.


STATE C 이슈가 지시문이 되어야 한다

같은 맥락에서 STATE C도 다시 봤다.

Builder가 3번 실패하면 GitHub 이슈가 자동 생성된다. 근데 그 이슈에 뭐가 들어있어야 내가 실제로 써먹을 수 있나.

1~3번 시도 코드와 에러, 페퍼가 분석한 실패 원인, 그리고 — Claude Code에게 주는 지시문이 이미 써져있어야 한다.

내가 할 일은 하나다. context.md 첨부하고 이슈 본문을 Claude Code에게 던지는 것. 내가 에러를 이해하는 게 아니라, 페퍼가 에러를 분석해서 다리를 놓아준다. 그게 나한테 맞는 바이브코딩이다.


Google I/O가 오늘 있었다

Gemini 3.5 Flash 출시. 기존 대비 절반 가격에 성능은 높다. Gemini 2.0 Flash는 6월 1일 종료 — 긴급 마이그레이션 항목으로 박았다.

그리고 구글이 Information Agents를 발표했다. 24시간 백그라운드에서 조건 충족 시 알림. 오늘 오전에 설계한

monitoring_tasks
+
proactive-worker
가 그거다. 방향이 맞다는 검증이 됐다.


오늘 코드는 없다. 그래도 페퍼는 자랐다.

내일은 구현 세션이다.