"AI한테 시키면 빨라요?" 자주 받는 질문이다. 빠르긴 했다. 그런데 처음엔 결과가 들쭉날쭉했다.
그냥 "이 기능 만들어줘" 하고 던지면, AI는 우리 도메인을 모르니 일반론과 환각으로 채웠다. 똑똑한데 우리 프로젝트의 기억이 없었다. 그래서 프로젝트마다 ref/ 폴더 하나를 두기 시작했다. AI의 기억을 내가 대신 만들어 두는 곳이었다. (완성형은 아니다. 지금도 굴리며 다듬는 중이다.)
ref 없이 vs 있을 때
차이는 금방 드러났다. "외부 사이트 신청 폼을 우리 시스템에 연동해줘" 할 때, ref가 없으면 AI는 폼 필드 이름을 그럴듯하게 지어냈다 — 실제와는 안 맞았다. 그 폼의 실제 코드를 ref에 긁어다 뒀더니, 추측 없이 그 구조 그대로 짰다. 차이는 '얼마나 똑똑한 모델이냐'가 아니라 '실물 자료가 옆에 있느냐'였다.
docs/ 와 ref/ 를 나눴다
docs/= 팀이 보는 정제된 공개 문서. git에 커밋.ref/= 나와 AI만 보는 작업용 원자료. gitignore.
런북엔 실제 접속 명령이, 데이터 샘플엔 원본이 들어 있었다. 공개 레포는 더럽히면 안 되지만 AI한텐 줘야 일을 제대로 했다. gitignore된 ref가 그 사이를 메웠다.
ref 안에 쌓은 것
- 기능 명세·기획서 — '무엇을' 만들지의 근거
- 데이터 샘플(JSON·엑셀) — 타입·엣지케이스를 추측이 아니라 실물로
- 외부 코드 덤프 — 연동할 폼·사이트의 실제 코드
- 런북 — 배포·마이그레이션 실명령을 복붙 가능한 형태로
- DB 스키마 — 테이블 관계의 단일 출처
- 조사 노트·PLAN — 작업 전 '현황 → 결정'을 적어둔 것
가장 효과 본 패턴: 조사가 산출물이 됐다
제일 효과 본 건 이거였다. 새 작업 전에 AI한테 먼저 '조사'를 시켜 ref에 문서로 남겼다. 외부 폼 여러 개가 우리 API로 정확히 뭘 보내는지 표로 정리시켰더니, 그 문서가 그대로 데이터 구조화 작업의 설계도가 됐다. 채널 하나를 통째로 긁어올 땐 수집 전략을 PLAN 문서로 먼저 쓰게 했고, 그게 곧 수집 스크립트의 명세가 됐다.
그러자 그 조사 문서가 다음 단계(설계·구현)의 입력이 됐다. AI는 매번 0에서 추측하지 않고, 쌓아둔 맥락 위에서 일했다. 환각이 줄고, 결정에 흔적이 남고, 다음에 같은 영역을 건드릴 때 재사용됐다.
ref만 컨텍스트가 아니었다 — 두 층으로 쌓았다
쌓다 보니 컨텍스트가 두 층이 됐다. ref가 '원자료(데이터·코드·조사)' 층이라면, 또 한 층은 CLAUDE.md와 .claude/rules/였다. "이 프로젝트에선 이렇게 한다"는 규칙을 영역별로 — 백엔드, 프론트, 공통, 프로젝트별 — 파일로 쪼개 두고(폴더 구조, 네이밍, 커밋·에러 처리 컨벤션 등), AI가 매번 따르도록 박아뒀다. ref가 '무엇을' 다룰지의 재료라면, 규칙은 '어떻게' 만들지의 기준이었다. 둘이 같이 있어야 결과물이 '내 코드'처럼 나왔다.
사실 AI만을 위한 게 아니었다
ref에 쌓은 조사·PLAN 문서는 미래의 나를 위한 것이기도 했다. 몇 달 뒤 같은 영역을 다시 만질 때, 그때의 맥락과 결정이 그대로 남아 있었다. AI 컨텍스트를 쌓는 일이, 곧 내 프로젝트 문서를 쌓는 일이었다.
빠른 게 다가 아니었다 — 품질이 따라왔다
AI 코딩은 흔히 '빠르지만 대충'이라고들 한다. 그런데 이런 하네스(ref + 규칙)를 깔고 나니 속도와 품질이 트레이드오프가 아니었다. 실제 자료에 맞춰 짜니 환각이 줄었고, 정해둔 컨벤션을 따르니 결과가 내 코드 품질에 수렴했다. 빠른 동시에, 믿고 쓸 만한 결과가 나왔다.
보완할 점
물론 숙제도 남았다. ref엔 크리덴셜이나 원본 데이터가 들어갈 수 있어, 보안은 앞으로 더 챙길 부분이다. 민감정보는 자리표시자로 빼고 시크릿은 따로 관리하기, 개인정보는 마스킹해서 넣기, gitignore에만 기대지 않고 시크릿 스캐너로 한 번 더 거르기 — 계속 들여다볼 생각이다.
남은 것
모델 성능 차이는 점점 좁혀진다. 결국 차이를 만든 건 'AI가 일할 맥락을 내가 얼마나 잘 떠먹여 줬느냐'였다.
"좋은 결과물은 좋은 프롬프트가 아니라, 잘 쌓아둔 컨텍스트에서 나온다."