InfoGrab DocsInfoGrab Docs

GitLab AI 지침 파일 리뷰

요약

코드 리뷰에 관한 더 폭넓은 조언과 모범 사례는 코드 리뷰 가이드를 참조합니다. .ai/ 아래 파일을 변경할 때마다 전담 리뷰가 필요합니다. 정제된 원칙에는 소비자가 하나 더 있습니다. 펜스 재생성은 정제 작업과 분리되어 있습니다.

코드 리뷰에 관한 더 폭넓은 조언과 모범 사례는 코드 리뷰 가이드를 참조합니다.

일반 프로세스#

.ai/ 아래 파일을 변경할 때마다 전담 리뷰가 필요합니다. 이 파일들은 AI 코딩 에이전트(GitLab Duo, Claude Code, OpenCode 및 AGENTS.md를 인식하는 기타 도구)가 이 리포지터리에서 작업할 때 어떻게 동작할지를 구성하므로, 실수가 하나의 런타임 코드 경로에만 영향을 주지 않고 모든 기여자의 에이전트 세션에 영향을 줍니다.

정제된 원칙에는 소비자가 하나 더 있습니다. .gitlab/duo/mr-review-instructions.yaml은 정제된 원칙에서 가져온 생성된 펜스를 담고 있으므로, 정제된 원칙을 변경하면 해당 원칙의 파일 필터와 일치하는 모든 머지 리퀘스트에 Duo가 게시하는 자동 리뷰 피드백도 함께 바뀝니다.

펜스 재생성은 정제 작업과 분리되어 있습니다. 정제된 원칙의 머지 리퀘스트는 .ai/principles/distilled/*.md 파일만 업데이트합니다. 머지된 후에는 별도의 CI/CD 잡이 머지된 master의 정제된 파일에서 순수 투영 방식으로 펜스를 조정하고(각 파일의 distilled_at_sha와 source_checksum 프런트 매터를 복사하며 정제를 다시 실행하지 않습니다), 자체 머지 리퀘스트를 엽니다. 이렇게 하면 팀의 정제 머지 리퀘스트와 펜스 업데이트를 독립적으로 머지할 수 있으므로, 어느 쪽도 상대방이 CI를 통과하기를 기다리지 않습니다.

.ai/ 파일을 변경하려면 AI 하네스 직접 책임자(DRI)의 승인이 필요합니다. 이 규칙은 .gitlab/CODEOWNERS의 "Monolith AI harness files" 블록에 반영되어 있습니다. 이 파일들은 광범위한 * 규칙의 승인은 필요하지 않지만, 각각 지정된 DRI의 승인이 필요합니다. 리뷰 규칙은 작업 항목 20880에서 추적합니다.

정제된 원칙 파일에는 승인 경로가 한 단계 더 있습니다. 각 파일은 단일 진실 공급원(Single Source Of Truth, SSOT) 문서를 소유한 팀도 소유하므로, 정제 변경은 해당 도메인 팀이 승인합니다. 자동 생성된 동기화 머지 리퀘스트 리뷰를 참조합니다.

.ai/ 파일의 구성#

.ai/ 디렉터리에는 네 가지 범주의 파일이 있으며, 범주마다 리뷰 방식이 다릅니다.

  • 직접 작성한 모듈: .ai/README.md, .ai/ci-cd.md, .ai/git.md, .ai/merge-requests.md, .ai/code-review.md입니다. 사람이 작성한 지침 문장이며, 리포지터리 루트의 AGENTS.md에서 참조합니다.
  • 정제된 원칙: .ai/principles/distilled/*.md입니다. AI 원칙 정제기가 docs.gitlab.com의 SSOT 문서에서 자동 생성합니다. 이 파일은 직접 편집하면 안 됩니다.
  • 베이스라인: .ai/principles/baselines/*.md입니다. 아직 docs.gitlab.com에서 다루지 않아 직접 선별한 리뷰 규칙이며, 동기화 중에 정제된 출력에 병합됩니다.
  • 정제 구성: .ai/principles/manifest.yml과 .ai/principles/distillation_prompt.md입니다. 정제기를 구동하는 라우팅 및 프롬프트의 SSOT입니다.

일반 리뷰 원칙#

파일 범주와 관계없이 모든 .ai/ 변경에 다음을 적용합니다.

  • 지침을 코드가 아니라 프롬프트로 취급합니다. 지침은 언어 모델이 읽는 것이며 실행되지 않습니다. 명확하고 명령형이며 모호하지 않은 규칙을 선호합니다. 에이전트가 잘못 해석할 수 있거나 다른 모듈과 모순되는 표현을 지적합니다.
  • 모든 에이전트 세션이 영향을 받는다는 점을 기억합니다. 점진적 롤아웃도, 기능 플래그도 없습니다. 지침 파일의 회귀는 모든 기여자의 에이전트 출력을 즉시 저하시킵니다.
  • 모호한 지침을 지적합니다. 배경 설명 문장 대신 구체적인 Do X / Don't do Y 규칙을 요청합니다. 모호한 지침은 모호한 에이전트 동작을 만듭니다.
  • 중복되거나 장황한 콘텐츠를 지적합니다. 지침 파일은 에이전트의 컨텍스트 창에 로드되므로, 이런 콘텐츠는 유용한 컨텍스트를 밀어내고 비용을 늘립니다. 중복 대신 간결한 규칙과 상호 참조를 요청합니다.
  • 루트 AGENTS.md가 참조하지 않는 새 모듈을 지적합니다.
  • CLAUDE.md에 있는 에이전트 지침을 지적합니다. 이 지침은 AGENTS.md에 있어야 합니다.
  • 옆에 CLAUDE.md가 없는 AGENTS.md와, @AGENTS.md 가져오기 외의 내용이 있는 CLAUDE.md를 지적합니다. Claude Code는 CLAUDE.md 또는 CLAUDE.local.md가 있으면 AGENTS.md를 건너뛰므로, 가져오기를 사용하면 모든 도구가 하나의 지침 세트를 공유합니다. 예외는 doc/ 아래의 CLAUDE.md로, 문서 린터에 필요한 markdownlint-disable과 vale off 주석도 함께 유지합니다.
  • 이중 단일 진실 공급원을 지적합니다. .ai/에 직접 작성한 규칙 대신, 정제기가 규칙을 생성할 수 있도록 SSOT 문서에 규칙을 작성하도록 요청합니다. 직접 작성한 규칙은 모두 그 규칙이 중복하는 문서와 어긋날 수 있습니다.

파일 범주별 체크리스트#

직접 작성한 모듈#

.ai/README.md, .ai/ci-cd.md, .ai/git.md, .ai/merge-requests.md, .ai/code-review.md의 경우:

  • 지침이 설명하는 실무에 비추어 정확하고 최신인지 확인합니다.
  • 다른 모듈 및 정제된 원칙과 모순되는지 확인합니다.
  • 루트 AGENTS.md가 새 모듈을 참조하는지, 그리고 각 AGENTS.md 옆에 @AGENTS.md 가져오기만 있는 CLAUDE.md가 있는지 확인합니다.
  • .ai/* 패턴이 gitignore 대상이므로 새 공유 모듈을 강제로 추가(git add --force)했는지 확인합니다.
  • 직접 작성한 모듈을 늘리기보다, 오래 유지되고 널리 적용되는 지침을 SSOT 문서로 옮겨 정제될 수 있게 하는 편을 선호합니다.

정제된 원칙#

.ai/principles/distilled/*.md의 경우:

  • 이 파일을 직접 편집하지 않습니다. SSOT 문서에서 다시 생성되며 <!-- Auto-generated ... do not edit manually --> 표시가 있습니다. 의도적인 직접 수정은 임시 방편으로 정제기 서비스 계정 브랜치에서만 허용되며, 머지 리퀘스트에 명시적으로 밝혀야 합니다.
  • 정제된 원칙의 내용을 바꾸려면 정제된 파일을 편집하지 않고 SSOT 문서(또는 일치하는 baselines/<name>.md)를 변경한 다음 동기화를 다시 실행합니다.
  • 정제된 변경이 원본 문서의 업데이트를 충실히 반영하는지, 그리고 원본이 뒷받침하지 않는 규칙을 추가하거나 누락하거나 모순되게 하지 않는지 확인합니다.
  • 정제된 출력에 원칙을 읽는 에이전트에게 의미 없는 리포지터리 내부 참조가 없는지 확인합니다. 예를 들어 .ai/principles/baselines/ 아래 경로나 다른 원칙 파일로 연결하는 링크가 해당합니다. 베이스라인 콘텐츠는 정제 후에도 원문 그대로 남으므로, 이런 참조가 정제된 파일로 새어 들어갑니다. 정제된 파일이 아니라 원본 베이스라인에서 수정합니다.
  • 프런트 매터(source_checksum, distilled_at_sha)는 그대로 둡니다. 이 값은 드리프트 감지에 사용됩니다. 직접 편집하면 재정제가 가려지거나 잘못 강제됩니다.
  • 생성된 CODEOWNERS 블록을 통해 변경이 SSOT를 소유한 올바른 팀으로 전달되는지 확인합니다.

베이스라인#

.ai/principles/baselines/*.md의 경우:

  • 그 규칙이 아직 SSOT에 자리가 없는 이유에 대한 근거를 요구합니다. 베이스라인은 예외적인 우회 수단이며, 에이전트 지침을 추가하는 기본 방법이 아닙니다.
  • 모든 베이스라인을 임시로 취급합니다. 규칙을 docs.gitlab.com으로 옮기는 후속 작업을 여는 편을 선호하며, 옮긴 뒤에는 베이스라인에서 제거해야 합니다.
  • 기존 SSOT 콘텐츠와 중복되거나 모순되는 베이스라인 규칙을 주의합니다. 이런 규칙은 이중 단일 진실 공급원을 만듭니다.
  • 베이스라인이 baselines/ 폴더나 다른 원칙 파일을 참조하지 않는지 확인합니다. 베이스라인 콘텐츠는 정제된 출력에 원문 그대로 병합되므로, 이런 상호 참조는 의미가 없는 채로 에이전트가 읽는 원칙에 새어 들어갑니다. 대신 독자를 정제된 원본으로 안내하거나 상호 참조를 삭제합니다.

정제 구성#

.ai/principles/manifest.yml과 .ai/principles/distillation_prompt.md의 경우:

  • manifest.yml의 경우 항목을 매니페스트 스키마에 따라 검증합니다. 필수 description, sources, owner_team, 올바른 file_filters, 다른 항목과 충돌하지 않는 team_slug가 해당합니다.
  • owner_team이 SSOT 문서를 실제로 소유한 팀으로 승인을 전달하는지 확인합니다.
  • 생성된 블록 안의 내용을 직접 편집하지 않습니다. 동기화는 .gitlab/CODEOWNERS에서 # BEGIN GENERATED와 # END GENERATED 주석으로, .gitlab/duo/mr-review-instructions.yaml에서 # >>> generated: <name>과 # <<< end generated: <name> 주석으로 이 블록을 구분합니다. 대신 동기화를 실행하여 다시 생성합니다.
  • distillation_prompt.md 변경은 이 디렉터리에서 위험도가 가장 높은 변경으로 취급합니다. 이 프롬프트가 모든 원칙의 정제 방식을 좌우하므로, 회귀가 발생하면 파일 하나가 아니라 다음 동기화에서 정제된 모든 파일의 품질이 조용히 떨어집니다. 프롬프트 변경은 그에 맞게 면밀히 검토합니다. 변경의 계기가 된 원칙 하나만이 아니라 전체 원칙에 미치는 영향을 따져 보고, 머지하기 전에 브랜치에서 --force로 일부 원칙을 정제하여 출력을 확인하는 편을 선호합니다.
  • distillation_prompt.md 변경은 카탈로그 플로를 다시 프로비저닝한 (gitlab-ai-principles-distiller-provision-flow) 뒤에야 적용된다는 점을 기억합니다. 파일을 머지하는 것만으로는 새 프롬프트가 배포되지 않습니다.

자동 생성된 동기화 머지 리퀘스트 리뷰#

주간 정제 동기화는 ai-agent와 documentation 레이블이 지정된 머지 리퀘스트를 자동으로 엽니다. 이 머지 리퀘스트는 자동으로 머지되지 않으며, 사람이 정제된 변경이 원본 문서의 업데이트를 충실히 반영하는지 확인한 뒤 머지해야 합니다.

팀별 머지 리퀘스트는 Draft로 열리고 GitLab Duo가 리뷰하는 동안 Draft로 유지됩니다. GitLab Duo 자동 리뷰는 Draft를 건너뛰므로 동기화가 명시적으로 리뷰를 요청합니다. 사람 리뷰어는 생성 시점에 지정되지만, Draft 상태는 기다리라는 신호입니다. 이후 동기화 실행이 채택된 머지 리퀘스트에 새 정제 콘텐츠를 게시하면, 사람이 이미 준비 완료로 표시했더라도 다시 Draft로 전환합니다. 새 콘텐츠에는 새로운 GitLab Duo 리뷰가 필요하기 때문입니다.

팀별 머지 리퀘스트의 승인은 생성된 파일별 CODEOWNERS 규칙을 통해 SSOT를 소유한 팀으로 전달됩니다. 리뷰할 때 다음을 수행합니다.

  • 정제된 파일의 프런트 매터에서 출력의 distilled_at_sha를 확인합니다.
  • 해당 SHA 시점의 .ai/principles/manifest.yml에서 원칙의 항목을 읽으며, 원본과 선택적 베이스라인도 포함합니다. 같은 SHA 시점의 관련 원본 섹션과 베이스라인을 읽습니다.
  • 의도적인 삭제를 확인해야 하면 원본 및 매니페스트 변경을 이전 distilled_at_sha와 비교합니다. 뒷받침되지 않는 추가뿐 아니라 누락된 규칙과 예외도 확인합니다.
  • 콘텐츠 손실 발견 사항마다 원본 경로, SHA, 관련 구절을 근거로 제시합니다. 뒷받침되지 않는 규칙의 경우 모순되는 구절을 인용하거나, 확인한 원본 섹션과 베이스라인을 밝히고 근거가 없는 이유를 설명합니다. 원본에서 의도적으로 삭제된 지침을 손실된 콘텐츠로 보고하지 않습니다.
  • 필요한 원본을 가져올 수 없으면 추측성 인라인 결함을 제기하지 않고 리뷰 요약에 그 한계를 밝힙니다.
  • 프런트 매터 체크섬이 직접 수정이 아니라 도구로 업데이트되었는지 확인합니다.

Code Review Flow는 참조된 파일을 최선을 다해 가져와 그 내용을 요약합니다. 참조 링크에만 의존하지 말고, 정제 및 펜스 조정 과정에서도 원본 검증 절차를 생성된 리뷰 지침 안에 그대로 유지합니다.

자동 리뷰 피드백 처리#

GitLab Duo는 이 머지 리퀘스트를 다른 머지 리퀘스트와 똑같이 리뷰합니다. diff가 사람이 작성한 코드가 아니라 문서 문장에서 기계적으로 생성되므로, 그 발견 사항은 신호 가치가 유난히 높습니다. 무시할 노이즈가 아니라 차례로 처리할 리뷰 대기열로 취급합니다.

주간 동기화 머지 리퀘스트에 자동 리뷰 발견 사항이 있으면 ai-principles-review-feedback 스킬을 사용하여 머지하기 전에 모든 발견 사항을 처리합니다.

스킬을 실행하는 메인테이너는 최신 리비전에 대한 GitLab Duo 리뷰가 성공하고 처리해야 할 발견 사항이 남아 있지 않은 뒤에만 머지 리퀘스트를 준비 완료로 표시합니다. 리뷰가 아직 실행 중이거나 실패했거나 최신 리비전을 포함하지 않으면 머지 리퀘스트를 Draft로 유지합니다. 사람 리뷰어는 머지 리퀘스트가 준비 완료가 된 후에 시작합니다.

예시:

Use the `ai-principles-review-feedback` skill to address every automated review finding on this weekly sync merge request.

발견 사항을 처리하기 전에 각각을 다음 네 가지 결과 중 정확히 하나로 분류합니다.

결과 의미 조치
Content defect 정제된 텍스트가 원본을 잘못 서술하거나 왜곡하거나 원본과 모순됩니다. 동기화 브랜치에서 수정합니다.
Content gap 정제 과정에서 원본이 뒷받침하는 규칙이 누락되었습니다. 동기화 브랜치에서 복원합니다.
Distiller defect 근본 원인이 이번 실행의 출력이 아니라 도구에 있습니다. 출력을 수정하고 정제기에 대한 이슈를 엽니다.
Judgment call 출력은 올바르지만 원본에 더 가까울 수 있습니다. 기록합니다. 반드시 조치가 필요한 것은 아닙니다.

수정할 때의 기준은 규칙이 어디에서 왔는지에 따라 다릅니다.

  • 베이스라인에서 파생된 규칙은 원문 그대로 복원합니다. 베이스라인 규칙은 표현 바꾸기 대상에서 제외되며, 동기화 도구가 규칙을 변경하거나 중복하거나 누락한 출력을 기계적으로 거부하고 재시도하므로 바꿔 쓴 문장은 게시될 수 없습니다.
  • 원본에서 파생된 수정은 충실하고 추적 가능하게 하되, 원본 표현을 그대로 복사하지 않습니다. 정제된 파일은 문서 문장이 아니라 구체적이고 확인 가능한 규칙을 담으므로, 그대로 복사하면 이 규약을 깨뜨리고 다음 실행에서 다시 바꿔 쓰이면서 불필요한 diff가 생깁니다.

발견 사항이 소수이고 국지적이면 동기화 브랜치에서 표적 수정을 선호합니다. 정제를 다시 실행하는 것은 느리고 비결정적이어서 발견 사항과 무관한 규칙에서 회귀가 생길 수 있습니다. 출력이 국지적이 아니라 전반적으로 잘못된 경우에 다시 실행합니다. 어느 쪽이든 정제된 파일에 대한 직접 수정은 머지 리퀘스트에 명시적으로 밝혀야 합니다.

브랜치의 수정 사항은 한 번의 푸시로 묶습니다. 프로젝트가 선택적 코드 오너 제거를 활성화하므로 파일을 푸시하면 그 파일의 코드 오너 승인이 취소되어, 푸시를 나누어 하면 이미 진행 중인 리뷰가 반복해서 무효화될 수 있습니다.

근본 원인이 도구에 있는 발견 사항은 매주 반복되므로 마무리까지 처리합니다.

  • 증상만이 아니라 메커니즘을 설명하는 이슈를 정제기에 대해 엽니다. 어떤 구성 요소가 어떤 입력에서 잘못된 출력을 만들었는지를 적습니다.
  • 정제 콘텐츠 손실을 추적하는 이슈 604659에 누락된 콘텐츠 사례를 각각 기록하여, 실패율을 일화가 아니라 측정 가능한 값으로 만듭니다.

펜스 조정 잡은 .gitlab/duo/mr-review-instructions.yaml만 변경하는 별도의 머지 리퀘스트를 엽니다. 이를 리뷰할 때는 펜스 지시문이 master에 있는 정제된 파일의 프런트 매터와 일치하는지 확인합니다. 이 잡은 정제를 실행하지 않으므로, 펜스 본문이 커밋된 정제 콘텐츠와 달라지는 일은 없어야 합니다.

이를 강제하는 ai-duo-review-instructions 가드는 형식이 잘못되었거나 고아가 된 펜스에서 항상 실패합니다. 이런 펜스는 조정과 무관하게 자체 ref에서 이미 깨져 있기 때문입니다. 펜스 _오래됨_은 심각도에 따라 처리합니다.

  • 조정 머지 리퀘스트와 펜스가 소유한 파일(Duo 지침 파일, 정제기 gem 또는 가드 스크립트)을 건드리는 머지 리퀘스트에서는 차단합니다. 이 경우 오래된 펜스는 작성자가 고칠 수 있는 실제 드리프트입니다.
  • master와 광범위한 매니페스트 트리거에 걸린 다른 머지 리퀘스트(팀의 정제 머지 리퀘스트 포함)에서는 차단하지 않는 경고입니다. 이 경우 오래됨은 조정 머지 리퀘스트가 펜스를 따라잡을 때까지 예상되는 일시적 상태입니다. 따라서 팀의 정제 머지 리퀘스트도, 관련 없는 doc/**/*.md 편집도 자체 ref에서 고칠 수 없는 펜스 오래됨 실패를 물려받지 않습니다.

정제 파이프라인의 전체 동작 방식(프로비저너, 동기화 바이너리, 일정, 매니페스트 스키마)은 .ai/principles/README.md를 참조합니다. 이 문서가 동기화 동작에 대한 단일 진실 공급원입니다.

관련 항목#

GitLab AI 지침 파일 리뷰

GitLab v19.6
원문 보기

요약

코드 리뷰에 관한 더 폭넓은 조언과 모범 사례는 코드 리뷰 가이드를 참조합니다. .ai/ 아래 파일을 변경할 때마다 전담 리뷰가 필요합니다. 정제된 원칙에는 소비자가 하나 더 있습니다. 펜스 재생성은 정제 작업과 분리되어 있습니다.

코드 리뷰에 관한 더 폭넓은 조언과 모범 사례는 코드 리뷰 가이드를 참조합니다.

일반 프로세스#

.ai/ 아래 파일을 변경할 때마다 전담 리뷰가 필요합니다. 이 파일들은 AI 코딩 에이전트(GitLab Duo, Claude Code, OpenCode 및 AGENTS.md를 인식하는 기타 도구)가 이 리포지터리에서 작업할 때 어떻게 동작할지를 구성하므로, 실수가 하나의 런타임 코드 경로에만 영향을 주지 않고 모든 기여자의 에이전트 세션에 영향을 줍니다.

정제된 원칙에는 소비자가 하나 더 있습니다. .gitlab/duo/mr-review-instructions.yaml은 정제된 원칙에서 가져온 생성된 펜스를 담고 있으므로, 정제된 원칙을 변경하면 해당 원칙의 파일 필터와 일치하는 모든 머지 리퀘스트에 Duo가 게시하는 자동 리뷰 피드백도 함께 바뀝니다.

펜스 재생성은 정제 작업과 분리되어 있습니다. 정제된 원칙의 머지 리퀘스트는 .ai/principles/distilled/*.md 파일만 업데이트합니다. 머지된 후에는 별도의 CI/CD 잡이 머지된 master의 정제된 파일에서 순수 투영 방식으로 펜스를 조정하고(각 파일의 distilled_at_sha와 source_checksum 프런트 매터를 복사하며 정제를 다시 실행하지 않습니다), 자체 머지 리퀘스트를 엽니다. 이렇게 하면 팀의 정제 머지 리퀘스트와 펜스 업데이트를 독립적으로 머지할 수 있으므로, 어느 쪽도 상대방이 CI를 통과하기를 기다리지 않습니다.

.ai/ 파일을 변경하려면 AI 하네스 직접 책임자(DRI)의 승인이 필요합니다. 이 규칙은 .gitlab/CODEOWNERS의 "Monolith AI harness files" 블록에 반영되어 있습니다. 이 파일들은 광범위한 * 규칙의 승인은 필요하지 않지만, 각각 지정된 DRI의 승인이 필요합니다. 리뷰 규칙은 작업 항목 20880에서 추적합니다.

정제된 원칙 파일에는 승인 경로가 한 단계 더 있습니다. 각 파일은 단일 진실 공급원(Single Source Of Truth, SSOT) 문서를 소유한 팀도 소유하므로, 정제 변경은 해당 도메인 팀이 승인합니다. 자동 생성된 동기화 머지 리퀘스트 리뷰를 참조합니다.

.ai/ 파일의 구성#

.ai/ 디렉터리에는 네 가지 범주의 파일이 있으며, 범주마다 리뷰 방식이 다릅니다.

  • 직접 작성한 모듈: .ai/README.md, .ai/ci-cd.md, .ai/git.md, .ai/merge-requests.md, .ai/code-review.md입니다. 사람이 작성한 지침 문장이며, 리포지터리 루트의 AGENTS.md에서 참조합니다.
  • 정제된 원칙: .ai/principles/distilled/*.md입니다. AI 원칙 정제기가 docs.gitlab.com의 SSOT 문서에서 자동 생성합니다. 이 파일은 직접 편집하면 안 됩니다.
  • 베이스라인: .ai/principles/baselines/*.md입니다. 아직 docs.gitlab.com에서 다루지 않아 직접 선별한 리뷰 규칙이며, 동기화 중에 정제된 출력에 병합됩니다.
  • 정제 구성: .ai/principles/manifest.yml과 .ai/principles/distillation_prompt.md입니다. 정제기를 구동하는 라우팅 및 프롬프트의 SSOT입니다.

일반 리뷰 원칙#

파일 범주와 관계없이 모든 .ai/ 변경에 다음을 적용합니다.

  • 지침을 코드가 아니라 프롬프트로 취급합니다. 지침은 언어 모델이 읽는 것이며 실행되지 않습니다. 명확하고 명령형이며 모호하지 않은 규칙을 선호합니다. 에이전트가 잘못 해석할 수 있거나 다른 모듈과 모순되는 표현을 지적합니다.
  • 모든 에이전트 세션이 영향을 받는다는 점을 기억합니다. 점진적 롤아웃도, 기능 플래그도 없습니다. 지침 파일의 회귀는 모든 기여자의 에이전트 출력을 즉시 저하시킵니다.
  • 모호한 지침을 지적합니다. 배경 설명 문장 대신 구체적인 Do X / Don't do Y 규칙을 요청합니다. 모호한 지침은 모호한 에이전트 동작을 만듭니다.
  • 중복되거나 장황한 콘텐츠를 지적합니다. 지침 파일은 에이전트의 컨텍스트 창에 로드되므로, 이런 콘텐츠는 유용한 컨텍스트를 밀어내고 비용을 늘립니다. 중복 대신 간결한 규칙과 상호 참조를 요청합니다.
  • 루트 AGENTS.md가 참조하지 않는 새 모듈을 지적합니다.
  • CLAUDE.md에 있는 에이전트 지침을 지적합니다. 이 지침은 AGENTS.md에 있어야 합니다.
  • 옆에 CLAUDE.md가 없는 AGENTS.md와, @AGENTS.md 가져오기 외의 내용이 있는 CLAUDE.md를 지적합니다. Claude Code는 CLAUDE.md 또는 CLAUDE.local.md가 있으면 AGENTS.md를 건너뛰므로, 가져오기를 사용하면 모든 도구가 하나의 지침 세트를 공유합니다. 예외는 doc/ 아래의 CLAUDE.md로, 문서 린터에 필요한 markdownlint-disable과 vale off 주석도 함께 유지합니다.
  • 이중 단일 진실 공급원을 지적합니다. .ai/에 직접 작성한 규칙 대신, 정제기가 규칙을 생성할 수 있도록 SSOT 문서에 규칙을 작성하도록 요청합니다. 직접 작성한 규칙은 모두 그 규칙이 중복하는 문서와 어긋날 수 있습니다.

파일 범주별 체크리스트#

직접 작성한 모듈#

.ai/README.md, .ai/ci-cd.md, .ai/git.md, .ai/merge-requests.md, .ai/code-review.md의 경우:

  • 지침이 설명하는 실무에 비추어 정확하고 최신인지 확인합니다.
  • 다른 모듈 및 정제된 원칙과 모순되는지 확인합니다.
  • 루트 AGENTS.md가 새 모듈을 참조하는지, 그리고 각 AGENTS.md 옆에 @AGENTS.md 가져오기만 있는 CLAUDE.md가 있는지 확인합니다.
  • .ai/* 패턴이 gitignore 대상이므로 새 공유 모듈을 강제로 추가(git add --force)했는지 확인합니다.
  • 직접 작성한 모듈을 늘리기보다, 오래 유지되고 널리 적용되는 지침을 SSOT 문서로 옮겨 정제될 수 있게 하는 편을 선호합니다.

정제된 원칙#

.ai/principles/distilled/*.md의 경우:

  • 이 파일을 직접 편집하지 않습니다. SSOT 문서에서 다시 생성되며 <!-- Auto-generated ... do not edit manually --> 표시가 있습니다. 의도적인 직접 수정은 임시 방편으로 정제기 서비스 계정 브랜치에서만 허용되며, 머지 리퀘스트에 명시적으로 밝혀야 합니다.
  • 정제된 원칙의 내용을 바꾸려면 정제된 파일을 편집하지 않고 SSOT 문서(또는 일치하는 baselines/<name>.md)를 변경한 다음 동기화를 다시 실행합니다.
  • 정제된 변경이 원본 문서의 업데이트를 충실히 반영하는지, 그리고 원본이 뒷받침하지 않는 규칙을 추가하거나 누락하거나 모순되게 하지 않는지 확인합니다.
  • 정제된 출력에 원칙을 읽는 에이전트에게 의미 없는 리포지터리 내부 참조가 없는지 확인합니다. 예를 들어 .ai/principles/baselines/ 아래 경로나 다른 원칙 파일로 연결하는 링크가 해당합니다. 베이스라인 콘텐츠는 정제 후에도 원문 그대로 남으므로, 이런 참조가 정제된 파일로 새어 들어갑니다. 정제된 파일이 아니라 원본 베이스라인에서 수정합니다.
  • 프런트 매터(source_checksum, distilled_at_sha)는 그대로 둡니다. 이 값은 드리프트 감지에 사용됩니다. 직접 편집하면 재정제가 가려지거나 잘못 강제됩니다.
  • 생성된 CODEOWNERS 블록을 통해 변경이 SSOT를 소유한 올바른 팀으로 전달되는지 확인합니다.

베이스라인#

.ai/principles/baselines/*.md의 경우:

  • 그 규칙이 아직 SSOT에 자리가 없는 이유에 대한 근거를 요구합니다. 베이스라인은 예외적인 우회 수단이며, 에이전트 지침을 추가하는 기본 방법이 아닙니다.
  • 모든 베이스라인을 임시로 취급합니다. 규칙을 docs.gitlab.com으로 옮기는 후속 작업을 여는 편을 선호하며, 옮긴 뒤에는 베이스라인에서 제거해야 합니다.
  • 기존 SSOT 콘텐츠와 중복되거나 모순되는 베이스라인 규칙을 주의합니다. 이런 규칙은 이중 단일 진실 공급원을 만듭니다.
  • 베이스라인이 baselines/ 폴더나 다른 원칙 파일을 참조하지 않는지 확인합니다. 베이스라인 콘텐츠는 정제된 출력에 원문 그대로 병합되므로, 이런 상호 참조는 의미가 없는 채로 에이전트가 읽는 원칙에 새어 들어갑니다. 대신 독자를 정제된 원본으로 안내하거나 상호 참조를 삭제합니다.

정제 구성#

.ai/principles/manifest.yml과 .ai/principles/distillation_prompt.md의 경우:

  • manifest.yml의 경우 항목을 매니페스트 스키마에 따라 검증합니다. 필수 description, sources, owner_team, 올바른 file_filters, 다른 항목과 충돌하지 않는 team_slug가 해당합니다.
  • owner_team이 SSOT 문서를 실제로 소유한 팀으로 승인을 전달하는지 확인합니다.
  • 생성된 블록 안의 내용을 직접 편집하지 않습니다. 동기화는 .gitlab/CODEOWNERS에서 # BEGIN GENERATED와 # END GENERATED 주석으로, .gitlab/duo/mr-review-instructions.yaml에서 # >>> generated: <name>과 # <<< end generated: <name> 주석으로 이 블록을 구분합니다. 대신 동기화를 실행하여 다시 생성합니다.
  • distillation_prompt.md 변경은 이 디렉터리에서 위험도가 가장 높은 변경으로 취급합니다. 이 프롬프트가 모든 원칙의 정제 방식을 좌우하므로, 회귀가 발생하면 파일 하나가 아니라 다음 동기화에서 정제된 모든 파일의 품질이 조용히 떨어집니다. 프롬프트 변경은 그에 맞게 면밀히 검토합니다. 변경의 계기가 된 원칙 하나만이 아니라 전체 원칙에 미치는 영향을 따져 보고, 머지하기 전에 브랜치에서 --force로 일부 원칙을 정제하여 출력을 확인하는 편을 선호합니다.
  • distillation_prompt.md 변경은 카탈로그 플로를 다시 프로비저닝한 (gitlab-ai-principles-distiller-provision-flow) 뒤에야 적용된다는 점을 기억합니다. 파일을 머지하는 것만으로는 새 프롬프트가 배포되지 않습니다.

자동 생성된 동기화 머지 리퀘스트 리뷰#

주간 정제 동기화는 ai-agent와 documentation 레이블이 지정된 머지 리퀘스트를 자동으로 엽니다. 이 머지 리퀘스트는 자동으로 머지되지 않으며, 사람이 정제된 변경이 원본 문서의 업데이트를 충실히 반영하는지 확인한 뒤 머지해야 합니다.

팀별 머지 리퀘스트는 Draft로 열리고 GitLab Duo가 리뷰하는 동안 Draft로 유지됩니다. GitLab Duo 자동 리뷰는 Draft를 건너뛰므로 동기화가 명시적으로 리뷰를 요청합니다. 사람 리뷰어는 생성 시점에 지정되지만, Draft 상태는 기다리라는 신호입니다. 이후 동기화 실행이 채택된 머지 리퀘스트에 새 정제 콘텐츠를 게시하면, 사람이 이미 준비 완료로 표시했더라도 다시 Draft로 전환합니다. 새 콘텐츠에는 새로운 GitLab Duo 리뷰가 필요하기 때문입니다.

팀별 머지 리퀘스트의 승인은 생성된 파일별 CODEOWNERS 규칙을 통해 SSOT를 소유한 팀으로 전달됩니다. 리뷰할 때 다음을 수행합니다.

  • 정제된 파일의 프런트 매터에서 출력의 distilled_at_sha를 확인합니다.
  • 해당 SHA 시점의 .ai/principles/manifest.yml에서 원칙의 항목을 읽으며, 원본과 선택적 베이스라인도 포함합니다. 같은 SHA 시점의 관련 원본 섹션과 베이스라인을 읽습니다.
  • 의도적인 삭제를 확인해야 하면 원본 및 매니페스트 변경을 이전 distilled_at_sha와 비교합니다. 뒷받침되지 않는 추가뿐 아니라 누락된 규칙과 예외도 확인합니다.
  • 콘텐츠 손실 발견 사항마다 원본 경로, SHA, 관련 구절을 근거로 제시합니다. 뒷받침되지 않는 규칙의 경우 모순되는 구절을 인용하거나, 확인한 원본 섹션과 베이스라인을 밝히고 근거가 없는 이유를 설명합니다. 원본에서 의도적으로 삭제된 지침을 손실된 콘텐츠로 보고하지 않습니다.
  • 필요한 원본을 가져올 수 없으면 추측성 인라인 결함을 제기하지 않고 리뷰 요약에 그 한계를 밝힙니다.
  • 프런트 매터 체크섬이 직접 수정이 아니라 도구로 업데이트되었는지 확인합니다.

Code Review Flow는 참조된 파일을 최선을 다해 가져와 그 내용을 요약합니다. 참조 링크에만 의존하지 말고, 정제 및 펜스 조정 과정에서도 원본 검증 절차를 생성된 리뷰 지침 안에 그대로 유지합니다.

자동 리뷰 피드백 처리#

GitLab Duo는 이 머지 리퀘스트를 다른 머지 리퀘스트와 똑같이 리뷰합니다. diff가 사람이 작성한 코드가 아니라 문서 문장에서 기계적으로 생성되므로, 그 발견 사항은 신호 가치가 유난히 높습니다. 무시할 노이즈가 아니라 차례로 처리할 리뷰 대기열로 취급합니다.

주간 동기화 머지 리퀘스트에 자동 리뷰 발견 사항이 있으면 ai-principles-review-feedback 스킬을 사용하여 머지하기 전에 모든 발견 사항을 처리합니다.

스킬을 실행하는 메인테이너는 최신 리비전에 대한 GitLab Duo 리뷰가 성공하고 처리해야 할 발견 사항이 남아 있지 않은 뒤에만 머지 리퀘스트를 준비 완료로 표시합니다. 리뷰가 아직 실행 중이거나 실패했거나 최신 리비전을 포함하지 않으면 머지 리퀘스트를 Draft로 유지합니다. 사람 리뷰어는 머지 리퀘스트가 준비 완료가 된 후에 시작합니다.

예시:

Use the `ai-principles-review-feedback` skill to address every automated review finding on this weekly sync merge request.

발견 사항을 처리하기 전에 각각을 다음 네 가지 결과 중 정확히 하나로 분류합니다.

결과 의미 조치
Content defect 정제된 텍스트가 원본을 잘못 서술하거나 왜곡하거나 원본과 모순됩니다. 동기화 브랜치에서 수정합니다.
Content gap 정제 과정에서 원본이 뒷받침하는 규칙이 누락되었습니다. 동기화 브랜치에서 복원합니다.
Distiller defect 근본 원인이 이번 실행의 출력이 아니라 도구에 있습니다. 출력을 수정하고 정제기에 대한 이슈를 엽니다.
Judgment call 출력은 올바르지만 원본에 더 가까울 수 있습니다. 기록합니다. 반드시 조치가 필요한 것은 아닙니다.

수정할 때의 기준은 규칙이 어디에서 왔는지에 따라 다릅니다.

  • 베이스라인에서 파생된 규칙은 원문 그대로 복원합니다. 베이스라인 규칙은 표현 바꾸기 대상에서 제외되며, 동기화 도구가 규칙을 변경하거나 중복하거나 누락한 출력을 기계적으로 거부하고 재시도하므로 바꿔 쓴 문장은 게시될 수 없습니다.
  • 원본에서 파생된 수정은 충실하고 추적 가능하게 하되, 원본 표현을 그대로 복사하지 않습니다. 정제된 파일은 문서 문장이 아니라 구체적이고 확인 가능한 규칙을 담으므로, 그대로 복사하면 이 규약을 깨뜨리고 다음 실행에서 다시 바꿔 쓰이면서 불필요한 diff가 생깁니다.

발견 사항이 소수이고 국지적이면 동기화 브랜치에서 표적 수정을 선호합니다. 정제를 다시 실행하는 것은 느리고 비결정적이어서 발견 사항과 무관한 규칙에서 회귀가 생길 수 있습니다. 출력이 국지적이 아니라 전반적으로 잘못된 경우에 다시 실행합니다. 어느 쪽이든 정제된 파일에 대한 직접 수정은 머지 리퀘스트에 명시적으로 밝혀야 합니다.

브랜치의 수정 사항은 한 번의 푸시로 묶습니다. 프로젝트가 선택적 코드 오너 제거를 활성화하므로 파일을 푸시하면 그 파일의 코드 오너 승인이 취소되어, 푸시를 나누어 하면 이미 진행 중인 리뷰가 반복해서 무효화될 수 있습니다.

근본 원인이 도구에 있는 발견 사항은 매주 반복되므로 마무리까지 처리합니다.

  • 증상만이 아니라 메커니즘을 설명하는 이슈를 정제기에 대해 엽니다. 어떤 구성 요소가 어떤 입력에서 잘못된 출력을 만들었는지를 적습니다.
  • 정제 콘텐츠 손실을 추적하는 이슈 604659에 누락된 콘텐츠 사례를 각각 기록하여, 실패율을 일화가 아니라 측정 가능한 값으로 만듭니다.

펜스 조정 잡은 .gitlab/duo/mr-review-instructions.yaml만 변경하는 별도의 머지 리퀘스트를 엽니다. 이를 리뷰할 때는 펜스 지시문이 master에 있는 정제된 파일의 프런트 매터와 일치하는지 확인합니다. 이 잡은 정제를 실행하지 않으므로, 펜스 본문이 커밋된 정제 콘텐츠와 달라지는 일은 없어야 합니다.

이를 강제하는 ai-duo-review-instructions 가드는 형식이 잘못되었거나 고아가 된 펜스에서 항상 실패합니다. 이런 펜스는 조정과 무관하게 자체 ref에서 이미 깨져 있기 때문입니다. 펜스 _오래됨_은 심각도에 따라 처리합니다.

  • 조정 머지 리퀘스트와 펜스가 소유한 파일(Duo 지침 파일, 정제기 gem 또는 가드 스크립트)을 건드리는 머지 리퀘스트에서는 차단합니다. 이 경우 오래된 펜스는 작성자가 고칠 수 있는 실제 드리프트입니다.
  • master와 광범위한 매니페스트 트리거에 걸린 다른 머지 리퀘스트(팀의 정제 머지 리퀘스트 포함)에서는 차단하지 않는 경고입니다. 이 경우 오래됨은 조정 머지 리퀘스트가 펜스를 따라잡을 때까지 예상되는 일시적 상태입니다. 따라서 팀의 정제 머지 리퀘스트도, 관련 없는 doc/**/*.md 편집도 자체 ref에서 고칠 수 없는 펜스 오래됨 실패를 물려받지 않습니다.

정제 파이프라인의 전체 동작 방식(프로비저너, 동기화 바이너리, 일정, 매니페스트 스키마)은 .ai/principles/README.md를 참조합니다. 이 문서가 동기화 동작에 대한 단일 진실 공급원입니다.

관련 항목#