Agent 친화 코드베이스 만들기: 안전장치부터 깔기

에이전트에게 코드를 맡기기 전에, 코드베이스부터 에이전트가 믿고 일할 수 있는 곳으로 만들어야 해요. 1년 된 Vooster 코드베이스에서 안전장치를 점검하고, Claude Code와 Codex가 서로의 테스트 전략을 반박하게 한 뒤, 커밋 12개짜리 PR로 첫 보강을 끝냈어요.

이 노트를 읽고 나면 할 수 있는 것

1. 프롬프트 한 줄로 내 코드베이스의 안전장치(포매터·린터·테스트·커밋 린트·git hook·CI)가 어디까지 깔려 있는지 점검하기
2. 내 의도(goal.md)와 AI가 덧붙인 의견을 나눠 문서로 남기고, 다른 에이전트에게 그 계획을 반박시키기
3. 커밋마다 acceptance criteria를 붙인 실행 계획을 Codex에 넘겨 구현을 맡기기

전체 2시간 15분 중 본론은 첫 1시간이고, 그 뒤는 Codex가 구현하는 동안 질문에 답하는 구간이에요. 다시보기: https://youtu.be/AuRDl5FGx-s

목차

• 새로 온 개발자를 어떻게 믿을까 ▶ 0:00:53
• 지금 깔린 안전장치 점검 ▶ 0:06:26
• 테스트의 적정량: E2E는 얇게, 순수 함수는 두껍게 ▶ 0:11:49
• goal.md에는 내 말만 남긴다 ▶ 0:17:08
• Codex와 Claude, 서로의 계획 반박시키기 ▶ 0:23:49
• 커밋마다 완료 조건을 붙여요 ▶ 0:50:17
• 이해는 Claude Code, 구현은 Codex ▶ 0:58:40
• 하네스 이전에 브레이크 ▶ 1:15:59
• 진행 문서, 교차 점검, 그리고 PR ▶ 1:50:17
• Q&A ▶ 1:23:13
• 오늘 해볼 것 ▶ 2:13:56

새로 온 개발자를 어떻게 믿을까 ▶ 0:00:53

이날 다룬 건 기능 개발이 아니라, 이미 있는 코드베이스를 AI 에이전트가 활약하기 좋은 상태로 바꾸는 방향이었어요. 기존 코드베이스에 에이전트를 도입할 때 가장 중요한 것은 코드베이스 자체가 정돈되는 거예요. ▶ 0:01:15

개발팀에 새 개발자가 들어왔다고 생각하면 쉬워요. 얼마나 유능한지와 상관없이, 그 사람의 결과물을 믿으려면 온보딩 기간이 필요해요. 매뉴얼이나 CI/CD 도구가 이미 깔려 있으면 훨씬 빨리 적응하고요. ▶ 0:02:16

코딩 에이전트도 똑같아요. 이런 게 준비되지 않은 코드베이스는 에이전트가 온보딩하기 어려워요.

그래서 할 일은 두 가지예요. 어지러운 코드·컨벤션·추론하기 어려운 아키텍처를 정리하고, 그다음 검증 도구를 까는 것이에요. ▶ 0:03:06 사람이든 에이전트든 누가 코드를 고쳐도 버그를 만들지 않았는지 보장해 주는 에어백이죠.

바이브코딩 시대에만 중요한 얘기도 아니에요. 마틴 파울러의 『리팩터링』도 테스트와 검증 가능한 환경이 코드를 고치는 데 필수라고 말해요. ▶ 0:03:51

예전엔 테스트 쓰기가 번거로워 속도를 위해 타협하기도 했어요. 에이전트 시대에는 코드 작성이 되게 저렴해졌으니 이런 것들은 안 깔 이유가 없죠. ▶ 0:04:21

실습 대상은 제가 운영하는 Vooster예요. 로그인(Clerk), 프로젝트 관리, 구독 결제가 붙은 서비스예요. ▶ 0:04:28