결론부터 말씀드리면

AI 에이전트(Claude Code)로 3개월 동안 업무 시스템을 혼자서 만들었습니다. 그동안의 커밋 수는 다음과 같습니다.

월	커밋 수
4월	11
...	月別コミット数のグラフ。4月11、5月5、6月257、7月85

첫 2개월 동안은 16 커밋. 6월 한 달에만 257 커밋.

이 차이를 만든 것은 저의 숙련도도, 모델의 업데이트도 아닙니다. 6월에 CLAUDE.md를 쓰기 시작한 것입니다.

이 기사는 그 CLAUDE.md에 "무엇을 써야 속도가 변하고, 무엇을 써도 무의미했는가"를, 실제로 86KB·1,400행까지 키워낸 경험을 바탕으로 정리한 것입니다.

만든 결과물의 규모감(전제 조건):

• 기간: 3개월 / 커밋 358회 / 약 81,000행 (Python 30,860 · Vue 47,629)
• 중소 제조 기업의 업무 시스템. 견적 → 수주 → 발주 → 출하 → 매출 집계
• 개발은 1인. 저는 엔지니어가 아니라 업무 담당자입니다

왜 처음 2개월은 멈춰 있었는가

코드를 작성하지 못해서가 아닙니다. 매번 똑같은 설명을 요구받았기 때문입니다.

• "이 화면의 파일은 어디에 있나요?"
• "인증은 어떻게 되어 있나요?"
• "백엔드(Backend)를 변경하면 재시작이 필요한가요?"

세션을 열 때마다 이런 질문을 받습니다. 대답합니다. 다음 날 또 질문을 받습니다.

설명이 번거로워지고, 착수가 귀찮아지며, 손이 멈춥니다. 이것이 4월과 5월의 모습입니다.

AI 에이전트는 실력은 확실하지만 어제의 회의에 참석하지 않은 외주 업체를 매일 한 명 고용하고 있는 것과 같습니다. 전달해야 할 것은 지시가 아니라 업무 매뉴얼이었습니다.

쓰면 속도가 변하는 것 (투자 대비 효과 순)

① 환경의 관습 — "건드리면 망가지는 곳"과 "반드시 해야 하는 절차"

최우선 사항. 이것만 써도 효과가 나타납니다.

제가 가장 먼저 쓴 것은 이것입니다.

## ⚠️ 백엔드 변경 후 컨테이너 재시작 (필수 규칙)
### 왜 `restart`로는 안 되는가
빌드된 이미지(Built image)가 업데이트되지 않기 때문.
...

이것을 쓰기 전, 저는 "수정했는데 반영이 안 된다"는 문제로 몇 시간이나 허비했습니다. AI는 "코드는 맞을 것입니다"라고 계속 말합니다. 실제로 코드는 맞았습니다.

코드를 읽으면 알 수 있는 것은 AI도 읽으면 압니다. 코드에 적혀 있지 않은 것(환경의 관습, 빌드 절차, 반영 방법)은 직접 써서 전달하는 것 외에는 전달할 방법이 없습니다.

이 부분이 CLAUDE.md의 존재 의의의 핵심입니다.

작성해야 할 것의 예:

• 변경 후 필요한 재시작·재빌드 절차
• 마이그레이션(Migration) 실행 및 되돌리는 방법
• 개발 서버 기동 방법 (저 자신도 3일 뒤면 잊어버립니다)
• "이 파일은 자동 생성되므로 직접 편집하지 마시오"와 같은 주의사항

② 업무 도메인 지식

AI가 원리적으로 알 수 없는 유일한 영역입니다.

저는 "자사 업무 지식"이라는 장을 만들어 사내 용어·업무 플로우(Flow)·업계 특유의 규칙을 적었습니다.

효과는 명확했습니다. "왜 이 항목이 필요한지"를 설명할 수 있는 AI가 됩니다.

반대로 이 부분을 전달하지 않으면, AI는 일반론적인 시스템을 만들려고 합니다. 범용 패키지가 현장에서 사용되지 않는 이유와 똑같은 일이 내재화 개발에서도 일어납니다.

구체적인 예로 하나, "우리 회사는 마감이 20일이다"라고 적어두지 않으면 월말 마감 구현이 나옵니다. AI는 사양을 추측하지 않고, 적혀 있지 않은 부분을 가장 일반적인 것으로 해석하기 때문입니다.

③ 설계 판단의 "이유(Why)"

저는 다음과 같은 장을 가지고 있습니다.

## 🧠 설계 판단 기록 (왜 이 구성인가)
### 인증에 "독자적 JWT"를 채택한 이유
### Vue 3 + Composition API를 선택한 이유
...

왜 효과가 있을까요? 적어두지 않으면 AI가 선의로 설계를 바꿔버리기 때문입니다.

3개월 차의 세션은 1개월 차의 논의를 알지 못합니다. "여기는 OAuth로 할까요?"라고 제안해 옵니다. 악의가 아니라 친절함 때문입니다. 그러니 "그 논의는 이미 끝났고, 결론은 이것이며, 이유는 이것이다"라고 적힌 종이를 놓아두는 것입니다.

이것을 작성한 이후로, 논의가 재점화되는 일이 거의 제로가 되었습니다.

④ 운영 환경의 전제

이것은 적지 않았던 탓에 큰 코를 다친 항목입니다.

로컬에서는 완벽하게 작동하던 채팅 기능이 운영 환경에서만 작동하지 않았습니다. 정확히는 "같은 프로세스에 연결된 사람들끼리만 대화할 수 있는" 매우 이해하기 어려운 방식으로 고장이 났습니다.

원인은 운영 환경에서 앱을 4개의 프로세스로 실행했기 때문입니다. 프로세스 내부의 메모리에 접속 정보를 가지고 있었기에, 다른 프로세스의 이용자에게는 전달되지 않았습니다.

AI의 잘못이 아닙니다. 제가 "운영 환경에서는 4개의 워커로 실행한다"라고 말하지 않았을 뿐입니다.

그래서 지금은 이렇게 적어두고 있습니다.

## 🏭 운영 환경에서는 uvicorn을 여러 개의 워커로 실행한다 (결정 사항)
## 📡 WebSocket 배포는 반드시 ws_bus.publish()를 사용한다 (다중 워커 대응)

개발 첫날에 작성해야 할 것:

• 프로세스 수 · 워커 구성
• 타임존 (후술하겠지만, 이 문제로 장표의 날짜가 하루 어긋났습니다)
• 공개 범위 (사내 전용 / 인터넷 공개)
• 예상 동시 이용자 수

나중에 전달하면 다시 작성해야 합니다. 저는 두 번이나 다시 작성했습니다.

⑤ 장애 대응 절차

로그 확인 방법, DB 접속 방법, 마이그레이션(Migration) 되돌리기, 백업으로부터의 복구.

제 자신을 위한 것이기도 하지만, 본질은 패닉 상태일 때 AI에게 올바른 절차를 실행시키기 위함입니다.

장애가 발생 중인 상황에서는 냉정한 지시를 내릴 수 없습니다. 절차서가 있다면 "CLAUDE.md의 장애 대응 절차에서 찾아봐"라는 한마디로 끝납니다.

쓰지 않아도 되는 것

이 부분이 의외로 중요합니다. CLAUDE.md는

방치하면 비대해지고, 비대해지면 읽히지 않게 됩니다.

❌ 코드를 읽으면 알 수 있는 것

함수 목록, 클래스 상속 관계, API 엔드포인트(Endpoint) 목록. 이것들은 작성하는 순간 낡은 정보가 되며, 게다가 AI는 스스로 읽을 수 있습니다.

저는 한때 이것을 작성했다가, 2주 만에 실제 내용과 차이가 생겨서 삭제했습니다.

❌ 범용적인 베스트 프랙티스 (Best Practice)

"SOLID 원칙을 따를 것", "테스트를 작성할 것". 모델은 이미 알고 있습니다. 토큰(Token) 낭비입니다.

❌ 기밀 정보

이것은 사고 방지 관점입니다. CLAUDE.md는

기본적으로 리포지토리(Repository)에 커밋됩니다. 저는 연락처 섹션에 다음과 같이 명시하고 있습니다.

⚠️ 중요: 연락처 · 전화번호 · 계약 번호는 CLAUDE.md에 쓰지 않는다.
이유: CLAUDE.md는 GitHub에 커밋되기 때문.
→ 패스워드 매니저(Password Manager)에 별도로 보관.

API 키, 패스워드, 서버의 IP도 마찬가지입니다.

운영의 3가지 규칙

1. 사양이 결정된 순간에 작성한다

나중에 몰아서 쓰려고 하면, 절대로 쓰지 않게 됩니다.

제 커밋 로그에는 CLAUDE.md: ~를 추가라는 단독 커밋이 여러 개 있습니다. 코드를 작성했다면, 그 자리에서 사양도 작성합니다.

2. AI에게 쓰게 한다

이번 변경 내용을 CLAUDE.md의 해당 부분에 추가해줘

직접 쓰는 것보다 빠르며, 게다가 AI가 나중에 읽기 쉬운 방식이 됩니다. 사람이 쓰면 사람을 위한 생략이 들어가 버립니다.

3. 구조를 유지한다

86KB까지 커지면, 구조가 없으면 자신도 찾을 수 없게 됩니다. 저는 이모지가 포함된 헤더로 장(Chapter)을 나누고 있습니다.

실제 목차 (발췌):

🎯 30초 만에 파악하는 ○○ 시스템
📦 리포지토리 운영
🚨 시크릿 관리 (항상 엄수)
...

이모지는 장식이 아니라, **긴 문서 속에서 장을 눈으로 빠르게 훑기 위한 인덱스(Index)**로서 기능하고 있습니다.

부수적인 효과: 인수인계 문서가 된다

예상하지 못했던 효과입니다.

사내 시스템을 혼자 만들면, 반드시 "이거, 당신이 없어지면 어떻게 되나요?"라는 이야기가 나옵니다. 기술적인 문제가 아니라, 경영 리스크로서 지적됩니다.

그래서 CLAUDE.md의 서두를 다음과 같이 고쳐 썼습니다.

> 이 문서는 AI 어시스턴트가 본 시스템을 이해하고 개수하기 위한
> 최우선 정보원입니다. 동시에, 계승자 · 다른 엔지니어 · 경영진이
> 시스템 전체를 파악하기 위한 입구이기도 합니다.

그리고 "계승자용 퀵 스타트(Quick Start)" 장을 추가했습니다.

Day 1 : 환경 설정
Day 2-3 : 시스템을 직접 만져보기
Day 4-7 : 코드 읽기 (CLAUDE.md → main.py → router → 1개 기능 추적)
...

AI를 위해 작성한 문서가 그대로 인간을 위한 인수인계 문서가 되었습니다.

게다가 아이러니하게도, 이 인수인계 문서를 작성하는 작업 자체가 AI의 특기 분야입니다. "현재 코드베이스를 전제로, 인수인계받을 사람을 위한 학습 절차를 작성해줘"라고 하면 80%는 해결됩니다.

요약

AI 에이전트(AI Agent)를 통한 개발은 프롬프트(Prompt)를 얼마나 잘 쓰느냐에 달려 있다고 생각하기 쉽습니다. 하지만 3개월간 경험하며 얻은 저의 결론은 달랐습니다.

결정적인 요소는 "AI가 매번 제로 베이스에서 생각하지 않아도 되는 환경"을 만들 수 있느냐입니다. 그리고 그것은 프롬프트 기술이 아니라, 문서 설계(Documentation Design)의 문제였습니다.

보충

이 글에 다 담지 못한 이야기 — 운영 릴리스 전에 발생한 결함(정기 태스크의 중복 실행, 번호 채번 중복, 동시 업데이트 시 데이터 유실), UTC 운영으로 인해 장표의 날짜가 하루 어긋난 건, 에러를 내지 않고 멈춰버린 자동 처리 이야기 — 는 3개월간의 실패와 대책으로서 note에 정리해 두었습니다.

질문이나 "우리 팀은 이랬다" 하는 이야기가 있다면, 댓글이나 X(@toda_naisei)로 연락해 주세요.

Discussion