문서용 AI 에이전트 지침 파일
GitLab v19.6요약
두 개의 별도 시스템이 워크플로의 서로 다른 단계에서 문서에 지침 파일을 적용합니다. 문서 스타일 가이드는 문서 표준의 단일 진실 공급원(Single Source Of Truth, SSOT)입니다. 에이전트가 로컬에서 문서를 작성하거나 편집할 때 다음 파일이 적용됩니다.
두 개의 별도 시스템이 워크플로의 서로 다른 단계에서 문서에 지침 파일을 적용합니다.
- 작성 및 편집 파일은 IDE 같은 로컬 환경에서 실행되는 AI 에이전트가 읽으며,
gitlab/doc디렉터리의 문서를 작성하거나 편집하는 데 사용됩니다. - 자동 리뷰 파일은 머지 리퀘스트를 푸시한 뒤 GitLab 플랫폼에서 실행되는 GitLab Duo Code Review가 읽습니다.
문서 스타일 가이드는 문서 표준의 단일 진실 공급원(Single Source Of Truth, SSOT)입니다. 작성 및 편집 파일은 스타일 가이드를 가리키거나 스타일 가이드에서 생성됩니다. 표준을 변경하려면 파일 자체가 아니라 스타일 가이드를 업데이트합니다.
작성 및 편집 파일#
에이전트가 로컬에서 문서를 작성하거나 편집할 때 다음 파일이 적용됩니다.
| 파일 | 목적 | 문서에 적용되는 방식 |
|---|---|---|
doc/AGENTS.md |
doc 디렉터리의 진입점입니다. 출력 요구 사항을 정하고 AI가 생성한 문서에서 피해야 할 흔한 실수를 나열합니다. |
문서 전용이며 모든 문서 작업에 자동으로 적용됩니다. |
doc/CLAUDE.md |
@AGENTS.md로 doc/AGENTS.md를 가져와 Claude Code가 같은 지침을 읽도록 합니다. |
문서 전용입니다. |
.ai/principles/distilled/documentation.md |
일반 문서 스타일과 완전성입니다. 스타일 가이드에서 gitlab-ai-principles-distiller가 자동 생성합니다. 이 파일을 직접 편집하지 않습니다. doc/AGENTS.md가 이 파일을 가리킵니다. |
문서 전용입니다. 에이전트가 작성하고 편집할 때 기준으로 삼는 표준입니다. |
.ai/principles/distilled/documentation-topics.md |
주제 유형(개념, 작업, 참조, 문제 해결, 튜토리얼)별 작성 지침입니다. 이 파일도 증류기가 생성합니다. 이 파일을 직접 편집하지 않습니다. | 문서 전용입니다. doc/ 아래의 파일에 적용됩니다. |
.ai/principles/distilled/documentation-api.md |
REST, GraphQL, CLI API를 문서화하는 표준(엔드포인트 참조 구조, 속성 표, cURL 예시)입니다. 이 파일도 증류기가 생성합니다. 이 파일을 직접 편집하지 않습니다. | 문서 전용입니다. doc/api/ 아래의 파일에 적용됩니다. |
.ai/principles/distilled/documentation-feature-lifecycle.md |
기능 상태와 수명 주기(기능 플래그, 실험 및 베타 상태, 버전 히스토리, 릴리스 노트)를 문서화하는 표준입니다. 이 파일도 증류기가 생성합니다. 이 파일을 직접 편집하지 않습니다. | 문서 전용입니다. 기능 플래그 및 수명 주기 변경에 적용됩니다. |
.ai/code-review.md |
에이전트가 따르는 일반 리뷰 방법론입니다. | 문서 리뷰에도 적용되는 일반 파일입니다. |
.ai/merge-requests.md |
일반 머지 리퀘스트 워크플로와 제출 전 체크리스트입니다. | 일반 파일입니다. Documentation 및 Screenshot 체크리스트 항목이 문서 머지 리퀘스트에 적용됩니다. |
.ai/code-review.md와 .ai/merge-requests.md는 문서만이 아니라 모든 변경에
사용하는 일반 파일입니다. 위 표에 표시한 섹션과 체크리스트만
문서 머지 리퀘스트에 적용됩니다.
모든 지침 파일이 어떻게 구성되고 로드되는지는
.ai/README.md를 참고합니다.
자동 리뷰 파일#
.gitlab/duo/mr-review-instructions.yaml은
GitLab Duo Code Review를 구성합니다. 머지 리퀘스트를 푸시하면 리뷰가
변경된 파일을 이 지침과 대조해 확인합니다.
문서에 적용되는 지침은 다음을 확인합니다.
- 문서 스타일: 미국 영어, 능동태, 문장형 대소문자, 마케팅 언어 금지, 스크린샷 크기 및 이름 지정 등의 스타일 규칙.
- API 문서: cURL 예시와 속성 표 같은 REST 관련 요구 사항.
- 포용적 언어처럼 모든 파일에 적용되는 일반 표준.
# >>> generated:와 # <<< end generated: 주석 사이의 지침 그룹은
생성된 것입니다. gitlab-ai-principles-distiller가 일치하는 증류된 원칙에서
내용을 복사하므로, 자동 리뷰는 작성 및 편집 파일과
같은 표준을 적용합니다. 기본 브랜치에서 증류된 원칙이 변경된 뒤
CI/CD 작업이 이 그룹을 다시 생성하므로 직접 편집하지 않습니다. 이 주석 밖의 그룹은
직접 관리합니다. 자세한 내용은
AI 지침 파일 리뷰를 참고합니다.
에이전트로 문서 작성#
GitLab Duo Chat이나 Claude Code 같은 로컬 AI 에이전트와 새 대화를 시작하면 작성 및 편집 파일이 자동으로 적용됩니다. 프롬프트에서 이 파일을 참조할 필요가 없습니다. 최상의 결과를 얻으려면 다음을 따릅니다.
- 문서 작업을 시작하기 전에 새 대화를 시작합니다.
- 변경은 로컬에서만 수행합니다. AI가 생성한 콘텐츠는 출력을 검토하고 반복 개선하기 전에 커밋하거나 푸시하지 않습니다.
리뷰를 요청하기 전에 콘텐츠를 확인하여 AI가 생성한 콘텐츠의 일반적인 품질 문제를 해결합니다.
리뷰 파일 업데이트#
스타일 가이드가 단일 진실 공급원입니다. 에이전트가 따르는 문서 표준을 변경하려면
작성 및 편집 파일이 아니라 문서 스타일 가이드를
업데이트합니다. gitlab-ai-principles-distiller는
스타일 가이드와 이 파일들이 증류되는 기반이 된 관련 문서 개발 페이지에서
다음 증류된 문서 파일을 자동으로 다시 생성합니다.
documentation.mddocumentation-topics.mddocumentation-api.mddocumentation-feature-lifecycle.md
이 파일은 gitlab 프로젝트에서만 사용됩니다. gitlab-ai-principles-distiller는 docs.gitlab.com에 문서를 게시하는 다른 프로젝트에는 구성되어 있지 않습니다.
.gitlab/duo/mr-review-instructions.yaml의 생성된 그룹은
같은 증류된 파일에서 다시 생성되므로, 스타일 가이드 변경이
별도의 편집 없이 자동 리뷰에 반영됩니다. 이 그룹은 직접 업데이트하지 않습니다.
스타일 가이드가 다루지 않는, AI가 생성한 콘텐츠의 반복되는 패턴을 발견하면 지침을 추가하는 머지 리퀘스트를 엽니다. 지침을 추가할 때는 다음 원칙을 따릅니다.
- 지침을 구체적이고 실행 가능하게 유지합니다.
Write concisely와 같은 모호한 지침은 피합니다. - 판단이 필요한 지침에는 예시를 사용합니다.
Avoid marketing language대신Avoid marketing language. For example, do not use "powerful" or "seamless"와 같은 예시를 제공합니다. - 변경을 테스트합니다. 새 대화를 시작하고 지침이 적용되는지 확인합니다.
AGENTS.md같은 AI 지침 파일을 업데이트하면 변경이 적용되려면 대화를 다시 시작해야 합니다. 기존 대화는 변경 사항을 자동으로 반영하지 않습니다.
문제 해결#
오류: Duo review instruction fences need attention#
ai-duo-review-instructions CI/CD 작업에서 fence가 Stale로 나열된 오류가 발생할 수 있습니다.
이 오류는 .gitlab/duo/mr-review-instructions.yaml의 생성된 그룹에 있는 메타데이터가
더 이상 증류된 원칙 파일과 일치하지 않을 때 발생합니다.
이 작업은 .gitlab/duo/mr-review-instructions.yaml, gitlab-ai-principles-distiller gem,
scripts/lint-duo-review-instructions.sh를 변경하는 머지 리퀘스트에서만
오래된 fence로 실패합니다.
작업이 같은 커밋을 확인하므로 실패한 작업을 재시도해도 오류가 해결되지 않습니다.
브랜치가 증류된 원칙을 변경하지 않는다면 기본 브랜치에서 fence가 오래된 상태입니다. 이 오류를 해결하려면 기본 브랜치의 fence를 조정(reconcile)합니다.
docs-sync/principles-reconcile-fences브랜치의 조정 머지 리퀘스트가 머지될 때까지 기다립니다.ai-principles-reconcile-fences작업은 기본 브랜치에서 증류된 원칙이 변경된 뒤 이 머지 리퀘스트를 열거나 업데이트합니다.- 열려 있는 조정 머지 리퀘스트가 없으면 최신 기본 브랜치 파이프라인에서
수동
ai-principles-reconcile-fences작업을 실행합니다. 작업을 실행하려면 기본 브랜치에 대한 머지 권한이 있어야 합니다. 이 권한이 없다면 메인테이너에게 실행을 요청합니다. 작업이 머지 리퀘스트를 열지 않으면 기본 브랜치의 fence는 최신 상태입니다. 이 경우 오래된 fence는 브랜치에서 비롯된 것입니다. - 브랜치를 기본 브랜치에 리베이스합니다.
오래된 fence가 브랜치의 변경에서 비롯된 것이라면 브랜치에서 fence를 다시 생성합니다.
-
리포지터리 루트에서 다음을 실행합니다.
bundle exec ruby gems/gitlab-ai-principles-distiller/bin/gitlab-ai-principles-distiller-sync reconcile-fences --workspace . -
fence가 최신 상태인지 확인합니다.
scripts/lint-duo-review-instructions.sh -
업데이트된
.gitlab/duo/mr-review-instructions.yaml파일을 커밋하고 푸시합니다.
reconcile-fences에 --push를 전달하지 않습니다.
이 옵션은 브랜치를 업데이트하는 대신 별도의 조정 머지 리퀘스트를 엽니다.