AI 코딩 도구에게 워드프레스 프로젝트를 맡겨 본 팀은 같은 불만을 말합니다 — “볼 때마다 다르게 짠다”. 원인은 대개 모델이 아니라 규약이 문서 밖에 있다는 것입니다. 사람 팀원이라면 리뷰에서 배웠을 것을, AI 는 매 세션 처음부터 시작합니다.
규약 문서에 담기는 것의 층위
- 결정에는 반드시 이유를 — “SEO 플러그인은 하나만” 뒤에 “둘이면 canonical 이 중복 선언된다” 가 붙어 있어야, AI 가 예외 상황에서도 취지에 맞게 판단합니다. 이유 없는 규칙은 곧 우회됩니다.
- 경계를 명시 — 수정 금지 디렉터리(부모 테마 · 벤더), 건드리면 안 되는 파일(자동 생성 CSS)을 목록으로. AI 의 일괄 치환이 벤더 트리로 번지는 사고는 경계 문서만으로 예방됩니다.
- 회귀 감지를 명령으로 — “인라인 스타일 금지” 옆에 그것을 잡아내는 grep 한 줄을 둡니다. 사람도 AI 도, 검사 가능한 규칙만 오래 지킵니다.
워드프레스에서 특히 적어 둘 것
- 훅 우선순위 관계 — 부모 테마 · 플러그인과의 로드 순서는 코드만 봐서는 안 보입니다.
- DB 에 사는 상태 — 어떤 설정이 옵션에 있고 어떤 것이 코드에 있는지. 이 구분이 없으면 AI 는 코드에 있어야 할 것을 화면에서 바꾸라고 안내합니다.
- 겪은 사고의 기록 — “이렇게 하면 이런 증상이 났다” 는 한 단락이, 같은 함정의 재발을 막는 가장 싼 보험입니다.
문서를 살아 있게 유지하는 규칙
규약 문서는 작업과 같은 커밋에서 갱신될 때만 신뢰를 유지합니다. “nice to have” 로 미루면 문서와 코드가 갈라지고, 갈라진 문서는 없느니만 못합니다 — AI 가 낡은 규약을 성실하게 따르기 때문입니다.
이 문서화가 콘텐츠 생산 쪽으로 이어지면 AI 콘텐츠 품질 게이트가 됩니다. 저희가 규약 기반으로 작업하는 실제 절차는 작업 과정에서 볼 수 있습니다.