AI 와 며칠만 함께 일해 보면 특정한 종류의 피로가 생깁니다. 어제 설명한 규약을 오늘 다시 설명하고, 지난주에 한 번 밟았던 함정을 이번 주에 또 밟는 일입니다. 세션은 매번 백지에서 시작하지만 프로젝트는 그렇지 않습니다. 프로젝트에는 결정과 그 근거, 이미 겪은 사고, 지켜야 할 규칙이 쌓여 있습니다.
이 격차를 메우는 방법은 단순합니다. 그 축적을 저장소 안의 문서 한 벌로 만들고, 작업을 시작할 때마다 함께 읽히는 것입니다. 이 사이트를 만드는 저장소가 정확히 그렇게 굴러갑니다.
무엇을 적는가 — 세 종류
결정은 반드시 근거와 함께 적습니다. “캐시 플러그인을 쓰지 않는다” 만 적혀 있으면 다음 사람(또는 다음 세션)은 그것을 취향으로 읽고, 편해 보이는 순간에 뒤집습니다. “서버 캐시와 무효화 타이밍이 어긋나 관리자와 방문자가 다른 화면을 보게 되므로 쓰지 않는다” 까지 적혀 있으면 뒤집을 때 무엇을 감수하는지를 알고 뒤집습니다. 결정을 지키게 만드는 것은 강제력이 아니라 근거입니다.
사고 기록은 원인보다 증상을 먼저 적는 것이 요령입니다. 다음에 같은 일이 생겼을 때 우리가 손에 쥐고 있는 것은 원인이 아니라 증상이기 때문입니다. “목록이 0건인데 필터의 개수 표시는 10” 처럼 화면에서 본 그대로 적어 두면, 몇 달 뒤 같은 화면을 보는 순간 검색이 됩니다. 원인만 적힌 기록은 이미 원인을 아는 사람에게만 읽힙니다.
규칙에는 검사 한 줄을 붙입니다
세 번째가 이 문서의 핵심입니다. 확인할 수 없는 규칙은 규칙이 아니라 소망입니다. 그래서 규칙을 적을 때마다 그 위반을 잡아내는 명령을 한 줄 함께 적습니다.
# 규칙: 컴포넌트 스타일에 색 리터럴을 쓰지 않는다 (토큰만 참조)
# 검사: 결과가 비어 있어야 한다
rg '#[0-9a-fA-F]{3,8}' assets/scss/components/
# 규칙: 웹훅 라우트에 nonce 를 걸지 않는다 (외부 호출이라 항상 실패한다)
# 검사: 결과가 비어 있어야 한다
rg 'wp_verify_nonce|check_ajax_referer' includes/gateway-*.php검사가 붙은 규칙에는 세 가지 이점이 한꺼번에 생깁니다. 첫째, 규칙이 모호하지 않게 됩니다 — 검사를 쓸 수 없다면 그 규칙은 아직 말이 덜 된 것입니다. 둘째, AI 든 사람이든 스스로 확인할 수 있습니다. 셋째, 나중에 누가 규칙을 어겼는지 논쟁하지 않고 명령을 돌려 보면 됩니다.
검사는 거창할 필요가 없습니다. 대부분은 “이 문자열이 이 디렉터리에 있으면 안 된다” 또는 “이 URL 이 200 을 돌려줘야 한다” 수준의 한 줄입니다. 중요한 것은 정교함이 아니라 존재입니다.
문서가 낡지 않게 하는 법
가장 흔한 실패는 문서가 코드보다 늦는 것입니다. 틀린 문서는 없는 문서보다 나쁩니다 — 읽는 쪽이 그것을 사실로 믿고 움직이기 때문입니다. 그래서 결정을 바꾸는 커밋과 문서를 고치는 커밋을 나누지 않는 편이 좋습니다. 같은 변경의 두 면이기 때문입니다.
분량도 관리 대상입니다. 문서가 커질수록 전부를 읽히기 어려워지므로, 더 이상 사실이 아닌 문장을 지우는 일이 새 문장을 더하는 일만큼 중요해집니다. “언젠가 참고할지도 모르니” 로 남긴 문단이 쌓이면 그 문서는 조용히 읽히지 않게 됩니다.
마지막으로 비밀 값은 절대 넣지 않습니다. 컨텍스트 문서는 널리 읽히라고 만든 것이고, 접속 정보나 API 키는 정확히 반대의 취급이 필요합니다. 문서에는 “키는 환경 설정 파일에 있고 저장소에 커밋하지 않는다” 는 규칙만 적습니다.
이렇게 관리된 문서는 AI 협업 도구이기 이전에 팀 문서입니다. 새로 합류한 사람이 첫날 읽는 것과 세션 시작에 읽히는 것이 같은 문서라면, 그 문서는 두 배로 값을 합니다.
이 방식으로 정리한 규약을 실제 요청에 어떻게 싣는지는 AI 활용 아카이브의 다른 글에서 다루고, 문서에 적히는 배포 · 환경 규칙은 로컬에서 프로덕션까지 연재와 겹칩니다. 운영 중인 사이트의 규약과 취약점을 함께 정리하고 싶다면 최적화 지원 사업에 진단이 포함돼 있습니다.