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

이 페이지는 팀이 doc/development/에 문서를 관리하고 있으며 해당 문서에서 AI 원칙을 추출하려는 경우에 사용하세요.

운영 런북(CI 변수, 서비스 계정 인증, 스케줄 복구)은 리포지터리 내 .ai/principles/README.md를 참조하세요.

동기화 작동 방식#

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

• .ai/principles/manifest.yml을 읽어 각 원칙이 어떤 문서 파일에서 파생되었는지 확인합니다.

• 각 원칙의 매니페스트 항목, 기준선(baseline), 소스 파일에 대한 체크섬 비교를 통해 드리프트를 감지합니다. 이를 기존 추출 파일의 front matter에 저장된 체크섬과 비교합니다.

• 드리프트가 발생한 각 원칙에 대해 GitLab Duo Agent Platform Workflow API를 호출하여 현재 소스 문서를 기반으로 추출 파일을 재생성합니다.

• 재생성된 파일을 .ai/principles/distilled/에 씁니다.

• 파일이 변경된 경우 머지 리퀘스트를 엽니다. 해당 머지 리퀘스트는 기본 브랜치를 타깃으로 하며 병합 전 사람의 승인이 필요합니다.

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

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

원칙 그룹 추가#

팀이 doc/development/ 아래의 문서를 소유하고 있으며 해당 문서에서 추출된 원칙을 생성하려는 경우 이 절차를 사용하세요.

원칙 그룹(예: Database, Frontend, Testing)은 일반적으로 매니페스트 내에서 group: 라벨을 공유하는 여러 관련 원칙을 포함합니다. 그룹의 각 원칙은 하나의 추출 파일이 됩니다.

다음의 경우 그룹을 여러 원칙으로 분리하세요:

• 소스 문서가 너무 커서 추출 파일을 한 번에 훑어보기 어려운 경우.

• 서로 다른 원칙이 서로 다른 리포지터리 경로에 적용되며 별도의 file_filters:가 유용한 경우.

예를 들어, Database 그룹은 database-fundamentals, database-migrations, database-schema, database-queries를 포함합니다.

• 각 원칙의 소스 파일을 식별하세요. 각 소스 파일은 다음을 충족해야 합니다:

  doc/development/ 아래에 있어야 합니다.

• 기본 브랜치에서 도달 가능해야 합니다(동기화는 기본 브랜치에서 읽습니다).

• 하나의 원칙에 속해야 합니다. 소스 파일이 여러 원칙에 적용된다면 각각에 나열하세요.

• 각 원칙에 대한 슬러그(slug)를 선택하세요. kebab-case를 사용하고 같은 그룹의 원칙에는 공통 접두사를 사용하세요. 예를 들어, database-migrations, database-schema, database-queries는 모두 database- 접두사와 group: Database 라벨을 공유합니다.

• .ai/principles/manifest.yml의 principles: 키 아래에 원칙당 하나의 항목을 추가하세요. 스키마는 매니페스트 참조를 확인하세요. 최소한 description, group, sources가 필요합니다.

• 선택 사항. 소스 문서에서 아직 다루지 않는 규칙을 위한 기준선 파일을 추가하세요.

• 매니페스트 변경 사항이 담긴 머지 리퀘스트를 여세요. .ai/ CODEOWNERS 규칙에 따라 리뷰가 AI 툴링 메인테이너에게 라우팅됩니다.

• 머지 리퀘스트가 병합된 후, 다음 예약된 동기화 실행 시 각 새 원칙에 대한 첫 번째 추출 파일이 .ai/principles/distilled/<slug>.md에 생성됩니다. 더 빨리 실행하려면 AI 툴링 메인테이너에게 스케줄을 수동으로 시작해 달라고 요청하세요.

• 생성된 파일을 검토하세요. 추출된 규칙이 문서를 충실히 반영하는지, 에이전트가 소스에 없는 규칙을 도입하지 않았는지 확인하세요.

효과적인 소스 문서 작성#

추출 프롬프트는 추출 파일을 생성할 때 소스 문서를 명령형 규칙으로 변환합니다. 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)로 시작하세요.

• 목록 항목당 하나의 관심사만 다루세요. 에이전트가 각 부분을 독립적으로 적용할 수 있도록 복합 규칙을 분리하세요.

• 설명적 문장을 피하세요. 에이전트는 기존 코드의 패턴과 충돌하면 "기능 플래그는 기본적으로 활성화됩니다"와 같은 문장을 무시합니다. 같은 내용을 규칙으로 작성하세요: "스펙에서 기능 플래그를 true로 스텁하지 마세요; 이미 기본적으로 활성화되어 있습니다."

• 예시를 구체적으로 유지하세요. 에이전트가 구문적으로 매칭할 수 있도록 코드, 파일 경로, 명령 예시에는 펜스드 코드 블록을 사용하세요.

• 추출 파일의 구조를 반영하기 위해 관련 규칙을 H3(### 섹션 이름) 제목 아래에 그룹화하세요.

예시#

가상의 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/baselines/<slug>.md에 추가하세요.

다음 동기화 실행 시 변경 사항이 반영됩니다.

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

표준 GitLab 되돌리기 플로를 통해 자동 생성된 머지 리퀘스트를 되돌리세요. 다음 동기화 실행 시 현재 소스 문서를 기반으로 파일이 재생성됩니다.

관련 항목#

• .ai/principles/manifest.yml에 대한 매니페스트 참조.

• 운영 런북을 위한 .ai/principles/README.md.

• 동기화를 구동하는 gem인 gems/gitlab-ai-principles-distiller.

• 추출 플로를 실행하는 플랫폼인 GitLab Duo Agent Platform.