GitLab은 doc/development/의 개발 규칙을 AI 에이전트가 변경을 계획하거나 구현할 때 로드하는 원칙 파일로 추출합니다. 그 결과로 생성되는 코드는 사람 리뷰어가 기대하는 규칙을 따릅니다.

팀이 doc/development/ 아래의 문서를 관리하고 있고 그 문서에서 AI 원칙을 추출하려 한다면 이 페이지를 참고합니다.

운영 런북(CI 변수, 서비스 계정 인증, 스케줄 복구)은 리포지터리의 .ai/principles/README.md를 참고합니다.

동기화 작동 방식#

gitlab-org/gitlab의 예약된 CI job 이 매주 실행되며 다음 단계를 수행합니다.

1. .ai/principles/manifest.yml을 읽어 각 원칙이 어떤 문서 파일에서 파생되는지 확인합니다.
2. 각 원칙의 매니페스트 항목, 기준선, 소스 파일에 대한 체크섬을 비교해, 기존 추출 파일의 front matter에 저장된 체크섬과 대조하는 방식으로 드리프트를 감지합니다.
3. 드리프트가 발생한 원칙마다 job 이 하나씩 있는 자식 파이프라인을 생성합니다.
4. 각 job에서 GitLab Duo Agent Platform Workflow API를 호출해, 현재 소스 문서를 기준으로 해당 원칙의 추출 파일을 다시 생성합니다.
5. 해당 job 들에서 재생성된 파일을 모아 .ai/principles/distilled/에 씁니다.
6. 변경된 파일이 있으면 머지 리퀘스트를 엽니다. 이 머지 리퀘스트는 기본 브랜치를 대상으로 하며 머지 전에 사람의 승인이 필요합니다.

각 원칙을 별도의 job에서 추출하면 원칙마다 타임아웃이 따로 적용되므로, 느린 원칙 하나 때문에 나머지 실행 결과가 버려지는 일이 없습니다.

추출은 서버 측에서 실행됩니다. 에이전트는 동기화가 실행되는 브랜치(주간 스케줄의 경우 기본 브랜치)에서 소스 파일을 읽습니다.

동기화를 구동하는 스크립트는 gitlab-ai-principles-distiller gem 입니다.

전체 흐름을 나타낸 다이어그램은 AI 원칙 추출 흐름을 참고합니다.

원칙 그룹 추가#

팀이 doc/development/ 아래 문서를 소유하고 있고 그 문서에서 추출한 원칙을 생성하려 할 때 다음 절차를 사용합니다.

원칙 그룹(예: Database, Frontend, Testing)은 대개 매니페스트에서 group: 레이블을 공유하는 여러 관련 원칙으로 구성됩니다. 그룹의 각 원칙은 하나의 추출 파일이 됩니다.

다음과 같은 경우 그룹을 여러 원칙으로 분리합니다.

• 소스 문서가 커서 추출 파일을 한 번에 훑어보기 어려운 경우.
• 원칙마다 적용되는 리포지터리 경로가 달라 file_filters:를 분리하는 편이 유리한 경우.

예를 들어 Database 그룹에는 database-fundamentals, database-migrations, database-schema, database-queries가 있습니다.

1. 각 원칙의 소스 파일을 파악합니다. 각 소스 파일은 다음 조건을 충족해야 합니다.
   • doc/development/ 아래에 있어야 합니다.
   • 기본 브랜치에서 접근할 수 있어야 합니다(동기화가 거기에서 읽습니다).
   • 하나의 원칙에 속해야 합니다. 소스 파일이 여러 원칙에 적용된다면 각 원칙 아래에 나열합니다.
2. 각 원칙의 슬러그를 정합니다. kebab-case를 사용하고 같은 그룹의 원칙에는 공통 접두사를 붙입니다. 예를 들어 database-migrations, database-schema, database-queries는 모두 database- 접두사와 group: Database 레이블을 공유합니다.
3. .ai/principles/manifest.yml의 principles: 키 아래에 원칙마다 항목을 하나씩 추가합니다. 스키마는 매니페스트 레퍼런스를 참고합니다. 최소한 description, group, sources가 필요합니다.
4. 선택 사항. 소스 문서가 아직 다루지 않는 규칙에 대해 기준선 파일을 추가합니다.
5. 매니페스트 변경 사항으로 머지 리퀘스트를 엽니다. .ai/ CODEOWNERS 규칙이 리뷰를 AI 도구 메인테이너에게 배정합니다.
6. 머지 리퀘스트가 머지되고 나면 다음 예약 동기화 실행에서 새 원칙마다 첫 추출 파일이 .ai/principles/distilled/<slug>.md 에 생성됩니다. 더 이른 시점에 실행하려면 파이프라인 스케줄에서 "AI principles distillation" 스케줄의 Run을 선택합니다. 이 실행은 동기화 job만 실행하고 생성된 파일로 머지 리퀘스트를 엽니다. 자세한 내용은 추출 수동 실행을 참고합니다.
7. 생성된 파일을 검토합니다. 추출된 규칙이 문서를 충실히 반영하는지, 에이전트가 소스에 없는 규칙을 만들어 내지는 않았는지 확인합니다.

효과적인 소스 문서 작성#

추출 프롬프트는 추출 파일을 생성할 때 소스 문서를 명령형 규칙으로 변환합니다. doc/development/ 아래 문서의 작성자가 내용을 DO NOT 규칙 형태로 표현할 필요는 없습니다.

소스 문서는 다음 조건을 갖출 때 더 나은 추출 결과를 냅니다.

• 제목이나 목록 항목마다 하나의 관심사만 다뤄, 추출기가 관심사마다 규칙 하나를 생성할 수 있게 합니다.
• 독자가 의도를 추론하지 않고도 구체적인 행동("X를 한다" 또는 "Y 를 하지 않는다")을 끌어낼 수 있을 만큼 규칙을 명확하게 서술합니다.

추출기를 구동하는 전체 프롬프트는 .ai/principles/distillation_prompt.md를 참고합니다.

추출기가 그대로 보존하는 기준선 규칙은 기준선 파일을 참고합니다.

기준선 파일#

.ai/principles/baselines/<slug>.md에 있는 기준선 파일은 팀이 의존하고 있지만 doc/development/ 아래 공개 문서에는 아직 반영되지 않은 규칙을 담습니다. 추출기는 소스 문서에서 추출한 규칙과 함께 기준선 내용을 생성된 원칙 파일에 그대로 복사합니다.

기준선 규칙을 추가하는 경우#

다음과 같은 경우에 기준선 규칙을 추가합니다.

• 문서가 설명하지 않는 도구 상태에 규칙이 의존하는 경우. 예를 들어 "db/schema_migrations/의 파일은 자동 생성되므로 마지막 줄바꿈이 필요하지 않다"는 규칙은 공개된 지침이 아니라 생성기의 동작에 의존합니다.
• 팀이 합의했지만 아직 doc/development/로 승격되지 않은 규칙이 있는 경우. 해당 규칙이 공개 문서에 반영될 때까지 기준선을 임시 보관 장소로 사용합니다.
• 에이전트도 함께 적용해야 할 리뷰어용 체크리스트 항목이 팀 내부 문서에 있는 경우.

가능하면 기준선 규칙을 소스 문서로 승격합니다. doc/development/ 에 있는 규칙은 더 넓은 독자가 검토할 수 있고 검색에 색인되며 원칙 동기화 밖의 프로젝트에도 도움이 됩니다.

기준선 파일이 추출 프로세스에서 작동하는 방식#

동기화가 원칙을 재생성할 때 추출기는 다음을 전달받습니다.

• 이전 버전에 어떤 내용이 있었는지에 대한 컨텍스트로서의 현재 추출 파일.
• 매니페스트 항목의 sources: 아래에 나열된 최신 소스 문서.
• "그대로 포함"으로 표시된 기준선 파일 내용.

추출 프롬프트는 추출기에 다음을 지시합니다.

• 소스 문서를 명령형 규칙으로 변환합니다.
• 기준선 내용은 표현을 바꾸지 않고 그대로 포함합니다.
• 소스 문서나 기준선 어느 쪽으로도 더 이상 추적되지 않는 현재 파일의 항목은 제거합니다.

결과는 .ai/principles/distilled/<slug>.md에 기록됩니다.

기준선 파일 스타일 가이드라인#

기준선 내용은 그대로 보존되므로 에이전트가 소비하는 형태로 작성합니다.

• 명령형으로 작성합니다. 금지 규칙은 DO NOT으로 시작하고 긍정 규칙은 동작 동사(Use, Prefer, Ensure, Include, Add, Set, Follow, Freeze, Pass, Wrap)로 시작합니다.
• 목록 항목마다 하나의 관심사만 다룹니다. 복합 규칙은 에이전트가 각 부분을 독립적으로 적용할 수 있도록 분리합니다.
• 서술형 문장은 피합니다. 에이전트는 "feature flags are enabled by default" 같은 서술이 기존 코드의 패턴과 충돌하면 이를 무시합니다. 같은 내용을 규칙으로 작성합니다. "DO NOT stub feature flags to true in specs. They are already enabled by default."
• 예시는 구체적으로 작성합니다. 에이전트가 구문으로 일치시킬 수 있도록 코드, 파일 경로, 명령 예시에는 펜스 코드블록을 사용합니다.
• 추출 파일의 구조를 반영하도록 관련 규칙을 H3(### Section name) 제목 아래에 묶습니다.

예시#

가상의 database-migrations 원칙에 대한 최소 기준선 파일은 다음과 같습니다.

### Schema migrations

- Files in `db/schema_migrations/` are auto-generated and do not require
  a trailing newline. DO NOT flag missing newlines on review.

### Batched background migration YAML

When creating `db/docs/batched_background_migrations/<name>.yml`, the
YAML must include:

- `migration_job_name: `
- `description: <one-line description>`
- `feature_category: <category symbol>`
- `milestone: '<X.Y>'`
- `gitlab_schema: <gitlab_main | gitlab_ci | gitlab_main_user | gitlab_main_org>`

자동 생성된 머지 리퀘스트 검토#

동기화 job은 원칙의 소스 문서가 변경될 때마다 머지 리퀘스트를 엽니다. 이 머지 리퀘스트는 다음과 같습니다.

• 원칙 동기화 서비스 계정이 작성합니다.
• 기본 브랜치를 대상으로 합니다.
• 변경된 원칙을 설명에 나열하고 각 원칙의 소스 파일 링크를 함께 제공합니다.
• 머지하려면 사람의 승인이 최소 한 건 필요합니다.

이러한 머지 리퀘스트를 검토할 때는 다음 세 가지에 집중합니다.

• 추출된 규칙이 소스 문서와 일치하는지. 에이전트가 소스에 없는 규칙을 만들어 내서는 안 됩니다.
• 규칙이 명령형으로 작성됐는지. 추출기는 명령형 규칙을 생성하도록 프롬프트를 받지만 간혹 서술형 산문으로 돌아갑니다.
• 기준선 규칙과 중복되는 규칙이 있는지. 중복이 있으면 기준선에서 해당 규칙을 제거합니다.

추출 결과에 노이즈가 있거나 없는 규칙이 만들어진다면 대개 소스 문서에서 고치는 것이 옳습니다. 추출기가 해석할 여지가 줄어들도록 소스의 표현을 더 명확하게 다듬습니다.

문제 해결#

동기화가 새 원칙에 대한 추출 파일을 생성하지 않은 경우#

동기화는 체크섬을 비교해 드리프트를 감지합니다. 매니페스트 항목이 참조하는 문서가 마지막 동기화 이후 변경되지 않았다면 추출이 실행되지 않습니다. 최초 생성을 강제하려면 다음 중 하나를 수행합니다.

• 소스 문서를 업데이트합니다. 다음 예약 실행에서 변경 사항을 감지합니다.
• AI 도구 메인테이너에게 해당 원칙을 대상으로 --force 옵션과 함께 추출기를 실행해 달라고 요청합니다.

추출 결과가 잘못되거나 노이즈가 많은 경우#

동기화 머지 리퀘스트가 아직 열려 있다면 원인이 된 추출과 같은 리뷰에서 수정이 처리되도록 해당 브랜치에 수정 사항을 커밋합니다.

• 소스 문서가 이미 명확하다면 .ai/principles/distilled/<slug>.md를 직접 수정합니다. 이 수정은 임시 조치로 취급하고 머지 리퀘스트에 명시해, 생성된 내용 사이에 수동 편집이 섞여 있다는 점을 리뷰어가 알 수 있게 합니다. 생성된 front matter의 체크섬이 드리프트 감지를 좌우하므로 front matter는 그대로 둡니다.
• 추출기가 잘못 해석할 여지가 있다면 소스 문서의 표현을 더 명확하게 다듬습니다.
• .ai/principles/baselines/<slug>.md에 기준선 파일을 추가합니다. 기준은 기준선 규칙을 추가하는 경우를 참고합니다.

추출 파일을 수정하면 그 파일만 고쳐집니다. 소스를 올바르게 고친 내용은 이후 추출에서도 유지됩니다.

동기화 머지 리퀘스트가 열려 있지 않다면 같은 변경 사항으로 직접 머지 리퀘스트를 엽니다.

잘못된 추출 결과를 되돌려야 하는 경우#

표준 GitLab 되돌리기 절차로 자동 생성된 머지 리퀘스트를 되돌립니다. 다음 동기화 실행에서 현재 소스 문서를 기준으로 파일이 다시 생성됩니다.

관련 주제#

• .ai/principles/manifest.yml에 대한 매니페스트 레퍼런스.
• 운영 런북에 대한 .ai/principles/README.md.
• 동기화를 구동하는 gem에 대한 gems/gitlab-ai-principles-distiller.
• 추출 흐름을 실행하는 플랫폼에 대한 GitLab Duo Agent Platform.