규칙은 문서에 있었고, 읽은 사람만 지켰다
「AX 여정」 연재 두 번째 글입니다. 약국용 서비스를 만드는 개발 조직에서 내가 AX를 맡아 2026년 6월부터 10월까지 깐 다섯 가지 가운데 첫 번째, 공통 AI 규칙을 다룹니다.
처음에는 흔한 방법을 썼습니다. 지켜야 할 것을 문서로 정리해 공지했습니다. 결과도 흔했습니다. 문서를 읽은 사람의 AI는 그 규칙대로 일했고, 읽지 않은 사람의 AI는 제멋대로 일했습니다. 같은 요청을 해도 사람마다 결과가 달랐습니다.
8월 27일에 남긴 한 문장이 방향을 바꿨습니다. 「사람 행동 패턴 변경은 최소화하고, AI 로 커버하도록」. 사람에게 규칙을 외우게 하는 대신, AI가 일을 시작할 때마다 규칙을 스스로 읽게 하면 됩니다.
CLAUDE.md — AI가 일을 시작할 때마다 먼저 읽는 메모
Claude Code는 터미널(글자로 명령을 입력하는 검은 창)에서 대화로 코드를 읽고 고치는 Anthropic의 AI 도구입니다. 작업 폴더 맨 위에 CLAUDE.md라는 파일이 있으면, 세션(Claude Code를 켜고 대화 한 판을 이어 가는 단위)을 시작할 때마다 그 내용을 먼저 읽고 일합니다. 새로 온 동료 책상에 붙여 두는 업무 메모와 비슷합니다. 다른 점은 이 동료가 메모를 한 번도 빼먹지 않는다는 것입니다.
그래서 규칙의 자리를 공지 게시판에서 CLAUDE.md로 옮겼습니다. 사람이 기억하지 않아도 그 폴더에서 일하는 모든 Claude가 같은 규칙을 읽습니다.
문제는 폴더가 하나가 아니라는 점이었습니다. 이 조직의 서비스 코드는 저장소 일곱 개에 나뉘어 있습니다. 저장소(repo)는 프로젝트 하나의 코드와 변경 기록을 담아 두는 공용 폴더입니다. 약국 사이트, 관리자 사이트, 앱 화면과 서버, 광고 서버까지 일곱 곳에 같은 규칙을 손으로 복사하면, 한 곳만 고치고 나머지를 잊는 일이 반드시 생깁니다.
규칙 저장소 한 곳에서 7개 repo로, 그리고 모든 PC로
그래서 원본을 한 곳에 모았습니다. 규칙만 담는 규칙 저장소를 따로 만들고, 서비스 저장소 일곱 곳에는 직접 쓰지 않고 복사본만 둡니다. 고칠 곳은 언제나 하나입니다.
복사는 사람이 하지 않습니다. 규칙 저장소의 공용 작업 줄기(develop 브랜치)에 변경을 올리면 GitHub Actions가 「Sync AI rules」라는 작업을 돌려 일곱 저장소에 규칙을 복사합니다. GitHub Actions는 저장소에 변화가 생기면 정해 둔 작업을 대신 실행해 주는 GitHub의 자동 실행 기능입니다. 화면에서 보듯 한 번에 2분에서 5분 남짓 걸리고, 10월 21일 기준 최근 95회가 모두 성공했습니다.
조직원 PC에는 최신본을 받아 오는 명령(git pull) 한 번 뒤에 새 세션부터 새 규칙이 적용됩니다. 규칙을 고친 사람이 할 일은 공지가 아니라 변경 하나를 올리는 것뿐입니다.
화면에 보이는 10월 20일 저녁부터 21일까지 이틀 사이에만 규칙을 다섯 번 고쳤습니다. 공지로 돌렸다면 다섯 번의 공지와 다섯 번의 「읽으셨나요」가 필요했을 일입니다.
core 규칙 8개에는 무엇을 쓰나
규칙 저장소는 두 층입니다. core에는 모든 저장소에 똑같이 들어가는 공통 규칙 문서 여덟 개가 있고, 그 아래에 저장소마다 다른 내용(쓰는 기술, 배포 방법)을 담은 프로젝트 규칙 일곱 개가 있습니다. 공통 규칙은 일하는 순서, AI의 행동 원칙, 이슈 작성법, 리뷰, 보안, 코드 스타일 같은 주제로 나뉩니다.
AI가 매번 읽는 규칙 가운데 가장 효과가 컸던 것은 세 가지입니다. 아래 표에 뜻과 이유를 함께 적습니다. 커밋은 변경을 하나의 묶음으로 저장해 두는 일이고, 브랜치는 원본을 건드리지 않고 작업하려고 따로 떼어 낸 갈래입니다.
규칙 문장은 짧고 검사할 수 있게 씁니다. 「신중하게 작업한다」는 AI가 지켰는지 알 수 없지만, 「요청 없이 push 하지 않는다」는 지켰는지 아닌지가 분명합니다. 지켰는지 확인할 수 있어야 다음 편에서 다룰 자동 검사로 옮길 수 있습니다.
| 규칙 | 뜻 | 왜 넣었나 |
|---|---|---|
| 요청 없이 push 하지 않는다 | 내 PC의 변경을 공용 저장소에 올리는 일(push)은 사람이 지시할 때만 한다 | 공용 저장소에 올라간 변경은 다른 사람의 작업과 서비스에 바로 닿는다 |
| 이슈 1건 = 브랜치 1 = 커밋 1 = push 1 | 할 일 하나에 작업 갈래 하나, 저장 하나, 올리기 하나 | 무엇이 왜 바뀌었는지 일감 번호 하나로 거슬러 올라갈 수 있다 |
| 완료 조건마다 테스트를 먼저 쓴다 | 다 됐다는 기준을 코드로 확인하는 시험을 고치기 전에 쓴다 | AI가 「다 했다」고 말할 때 그 말을 시험이 대신 확인한다 |
규칙은 부탁이다 — 그래서 다음 단계가 필요했다
규칙 저장소로 바뀐 것은 일의 모양입니다. 규칙을 바꾸고 싶은 사람은 공지 대신 변경 제안을 하나 올립니다. 화면 속 변경 메시지에 「AI 리뷰 반복 지적 반영」이 여러 번 보이는 것도 그래서입니다. AI 리뷰(변경 제안을 AI가 먼저 읽고 문제를 짚어 주는 검토)에서 같은 지적이 되풀이되면 그것이 다음 날 규칙 한 줄이 됩니다. 이 순환은 연재 6편 「매일 회고」에서 자세히 다룹니다.
한계도 분명했습니다. CLAUDE.md는 AI에게 하는 부탁입니다. 대부분 지키지만 늘 지킨다는 보장은 없고, 개인이 자기 PC에서 다른 설정을 덧붙이면 결과가 또 달라집니다.
그래서 두 번째 단계로 넘어갔습니다. 규칙 가운데 꼭 지켜야 하는 것은 부탁이 아니라 끌 수 없는 설정으로 바꿨습니다. 다음 편 「Claude Team 관리 설정」이 그 이야기입니다.
오늘 해 볼 한 가지 — CLAUDE.md에 규칙 세 줄
Claude Code를 쓰고 있다면 작업 폴더 맨 위에 CLAUDE.md 파일을 만들고 아래 세 줄을 넣어 보십시오. Claude Code 안에서 /init 을 입력하면 폴더를 읽고 CLAUDE.md 초안을 만들어 주니, 그 끝에 덧붙여도 됩니다.
저장한 뒤 새 세션을 열고 「지금 읽은 이 프로젝트의 규칙을 말해 줘」라고 물어보십시오. 세 줄을 그대로 말하면 적용된 것입니다.
폴더가 여럿이고 모든 작업에 같은 규칙을 쓰고 싶다면, 내 PC 전체에 적용되는 ~/.claude/CLAUDE.md 에 넣으면 됩니다. 팀 단위로 넓히는 순간 필요한 것이 이 글의 규칙 저장소입니다.
# 이 프로젝트의 규칙
- 내가 시키기 전에는 push 하지 않는다.
- 고치기 전에 완료 조건을 확인하는 테스트를 먼저 쓴다.
- 모르는 사실은 지어내지 말고 「미확인」이라고 적는다.