AI 개발 원칙 매니페스트 참조
GitLab v19.1원칙 동기화는 .ai/principles/manifest.yml 을 읽어 생성할 원칙, 각 원칙이 파생된 소스 파일, 자동 생성된 머지 리퀘스트를 여는 방법을 결정합니다. 온보딩 플로에 대한 내용은 AI 개발 원칙을 참조하세요.
원칙 동기화는
.ai/principles/manifest.yml
을 읽어 생성할 원칙, 각 원칙이 파생된 소스 파일, 자동 생성된 머지 리퀘스트를 여는 방법을 결정합니다.
온보딩 플로에 대한 내용은 AI 개발 원칙을 참조하세요.
최상위 키#
| 키 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| auto_mr | map | 예 | 예약된 동기화에서 열리는 머지 리퀘스트 설정. |
| principles | map | 예 | 원칙 슬러그에서 원칙 항목으로의 맵. Principle entry 참조. |
| static_entries | list | 아니오 | 에이전트 컨텍스트 로딩 스킬에 포함되는 수동으로 관리되는 파일 목록. |
Principle entry#
principles: 아래의 각 키는 슬러그입니다. 값은 다음 키를 가진 맵입니다:
| 키 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| description | string | 예 | 에이전트 라우팅 테이블에 사용되는 한 줄 요약. 대문자로 시작하며 마침표로 끝내지 않습니다. |
| group | string | 예 | 라우팅 테이블에서 관련 원칙을 묶는 데 사용되는 그룹 라벨. 예: Database, Backend, Frontend. |
| sources | list of maps | 예 | 원칙의 소스 문서 파일 목록. Source entry 참조. |
| file_filters | list of strings | 아니오 | 원칙이 적용되는 리포지터리 경로를 식별하는 Glob 패턴. 동기화에서 이를 사용하여 드리프트 탐지 범위를 지정합니다. |
| baseline | string | 아니오 | 수작업으로 관리되는 규칙이 포함된 파일 경로. 디스틸러는 baseline 콘텐츠를 원문 그대로 보존합니다. Baseline files 참조. |
| prerequisite | boolean | 아니오 | true일 경우, 라우팅 테이블은 이 원칙을 같은 그룹의 다른 모든 원칙에 대한 선행 조건으로 표시하고, 디스틸러는 해당 그룹 내 선행 조건이 아닌 모든 디스틸 파일에 참조 노트를 추가합니다. 기본값: false. |
| owner_team | string | 아니오 | 계획 중. 이 원칙의 자동 생성된 머지 리퀘스트 검토를 담당하는 팀을 식별합니다. 이슈 599920에서 추적 중. |
Source entry#
sources: 의 각 항목은 다음 키를 가진 맵입니다:
| 키 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| path | string | 예 | 리포지터리 루트를 기준으로 한 소스 문서 파일의 리포지터리 경로. |
| url | string | 예 | 소스 파일의 docs.gitlab.com 표준 URL. 디스틸된 파일이 이 URL로 다시 링크되어 검토자가 게시된 문서에서 규칙을 확인할 수 있습니다. |
Auto-merge request 설정#
auto_mr: 맵은 예약된 동기화가 머지 리퀘스트를 여는 방법을 제어합니다:
| 키 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| branch_prefix | string | 예 | 소스 브랜치 이름의 접두사. 동기화 시 실행 날짜가 추가됩니다. |
| title_template | string | 예 | 머지 리퀘스트 제목 템플릿. %{date} 보간을 지원합니다. |
| labels | list of strings | 예 | 머지 리퀘스트에 적용되는 라벨 목록. |
| remove_source_branch | boolean | 예 | true일 경우, 머지 리퀘스트가 머지된 후 소스 브랜치가 삭제됩니다. |
Static entries#
static_entries: 아래에 나열된 파일은 에이전트 컨텍스트 로딩 스킬에서 참조되지만 동기화에 의해 생성되지는 않습니다. 소스 문서에서 파생되지 않은 .ai/ 아래의 수동으로 관리되는 주제별 모듈에 이 목록을 사용하세요.
| 키 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| description | string | 예 | 로딩을 트리거하는 작업 설명. 예: Git, commits, 또는 branches. |
| path | string | 예 | 리포지터리 루트를 기준으로 한 파일의 리포지터리 경로. |
예시#
최소 Principle entry#
principles:
rest-api:
description: REST API design and conventions
group: API
sources:
- path: doc/development/api_styleguide.md
url: https://docs.gitlab.com/development/api_styleguide/
모든 필드를 포함한 Principle entry#
principles:
database-migrations:
description: Database migration patterns and zero-downtime safety
group: Database
prerequisite: false
file_filters:
- 'db/migrate/**/*.rb'
- 'db/post_migrate/**/*.rb'
baseline: .ai/principles/baselines/database-migrations.md
sources:
- path: doc/development/migration_style_guide.md
url: https://docs.gitlab.com/development/migration_style_guide/
- path: doc/development/database/avoiding_downtime_in_migrations.md
url: https://docs.gitlab.com/development/database/avoiding_downtime_in_migrations/
Auto-merge request 블록#
auto_mr:
branch_prefix: docs-sync/principles
title_template: "Update AI development principles from SSOT (%{date})"
labels:
- ai-agent
- documentation
- type::maintenance
remove_source_branch: true
Static entry#
static_entries:
- description: Git, commits, or branches
path: .ai/git.md
유효성 검사#
디스틸러는 로드 시 매니페스트의 유효성을 검사하고 다음과 같은 경우 오류와 함께 중단합니다:
-
auto_mr:블록이 없거나 필수 키 중 하나라도 누락된 경우. -
원칙에
sources:키가 없거나sources:가 비어 있는 경우.
이 유효성 검사는 머지 시가 아닌 동기화 시에 실행됩니다: 잘못된 매니페스트 항목은 해당 항목을 도입한 머지 리퀘스트를 차단하는 것이 아니라 다음 예약된(또는 수동) 동기화 실행을 실패하게 만듭니다.
관련 항목#
-
온보딩 플로에 대한 AI 개발 원칙.
-
라이브 매니페스트에 대한
.ai/principles/manifest.yml. -
매니페스트를 사용하는 gem에 대한
gems/gitlab-ai-principles-distiller.