AI 원칙 증류 흐름
GitLab v19.6요약
주간 동기화는 문서에서 AI 개발 원칙을 증류합니다. 단계별 설명은 동기화 작동 방식을 참고합니다. 각 동기화 실행은 드리프트 감지로 시작하여 증류된 파일을 업데이트하는 머지 리퀘스트로 끝납니다. 실행은 두 개의 파이프라인에 걸쳐 이루어집니다.
주간 동기화는 문서에서 AI 개발 원칙을 증류합니다. 매니페스트, 증류기 gem, 동기화 일정을 변경하기 전에 이 흐름을 검토합니다.
단계별 설명은 동기화 작동 방식을 참고합니다.
증류 흐름#
각 동기화 실행은 드리프트 감지로 시작하여 증류된 파일을 업데이트하는 머지 리퀘스트로 끝납니다.
실행은 두 개의 파이프라인에 걸쳐 이루어집니다. generate 작업이 드리프트를 검사하고 영향을 받는 원칙마다 증류 작업 하나씩을 포함한 자식 파이프라인을 내보냅니다. 이 작업들은 병렬로 실행된 다음 게시를 수행하는 단일 collect 작업으로 다시 모입니다.
소스 코드 보기
%%{init: { "fontFamily": "GitLab Sans" }}%%
flowchart TD
accTitle: AI principles distillation flow
accDescr: Flowchart of the weekly sync run, from drift detection through merge request creation
Start([Weekly scheduled CI job]) --> Load
Load[Load manifest.yml] --> Drift
Drift{Checksum matches<br/>distilled file front matter?}
Drift -->|Yes| UpToDate[Principle is up to date]
Drift -->|No| Affected[Principle needs an update]
UpToDate --> Generate
Affected --> Generate
Generate[Generate child pipeline:<br/>one distill job per affected principle]
Generate --> Validate
subgraph child [Child pipeline: one job per principle]
Validate{Source and baseline<br/>files exist?}
Validate -->|No| Fail([Fail: missing source path])
Validate -->|Yes| Distill
Distill[Call GitLab Duo Agent Platform<br/>Workflow API] --> Assemble
Assemble[Assemble distilled file<br/>and absolutize links] --> Meaningful
Meaningful{Content changed?}
Meaningful -->|No| Unchanged[Record 'unchanged'<br/>with new checksum checkpoint]
Meaningful -->|Yes| Updated[Record 'updated'<br/>with new checksum front matter]
end
Fail --> Collect
Unchanged --> Collect
Updated --> Collect
Collect[Collect job: fan in every<br/>principle's artifact]
Collect --> AnyUpdated
AnyUpdated{Any updated principles<br/>or checkpoints?}
AnyUpdated -->|No| Done([Exit: nothing to publish])
AnyUpdated -->|Yes| MR
MR[Open merge requests<br/>targeting the default branch] --> Review([Human approval and merge])</code></pre></details></div>
변경되지 않은 원칙#
소스가 바뀌었다고 해서 증류된 규칙이 항상 바뀌는 것은 아닙니다. 증류에서
의미 있는 변경이 나오지 않으면 collect 작업은 source_checksum과 distilled_at_sha
프런트 매터만 업데이트하는 메타데이터 머지 리퀘스트를 엽니다. 이 머지 리퀘스트가 머지되면
소스가 다시 바뀔 때까지 드리프트 감지가 해당 원칙을 건너뜁니다. 이 과정이 없으면
예약된 실행마다 같은 입력을 다시 증류하게 됩니다.
각 실행은 열려 있는 메타데이터 머지 리퀘스트를 재사용합니다. 증류 작업이 읽은 뒤
기본 브랜치의 증류된 파일이 바뀌었다면 collect 작업은 해당 원칙을 건너뛰고,
다음 예약 실행이 그 원칙을 다시 평가합니다.
실행을 분리한 이유#
예전에는 모든 원칙을 공유된 2시간 예산 아래 하나의 CI 작업 안에서 증류했습니다.
잘못된 콘텐츠로 실패하는 원칙은 재시도 백오프에 약 20분을 소모하며, 그 시간이
다른 모든 원칙에도 부과되었습니다. 2026-07-30에는 게시 단계에 도달하지 못해
이 작업이 시간 초과로 종료되었고, 성공적으로 증류된 원칙 19개가 폐기되었습니다.
각 원칙에 자체 작업을 주면 자체 시간 제한이 생기므로, 느린 원칙 하나가
나머지 실행을 더 이상 위협하지 않습니다. 동시 실행 수는 CI 리소스 그룹으로
4개로 제한되므로, 공유 GitLab Duo Agent Platform 스케줄러에 부하가 추가되지 않습니다.
게시는 여전히 단일 작업입니다. 이 작업은 원칙을 소유 팀별로 묶고
각 팀의 브랜치를 하나의 공유 작업 트리를 기준으로 만들기 때문에
같은 방식으로 분리할 수 없습니다.
불완전한 실행#
collect 작업은 증류에 실패한 원칙과, 러너 중단이나 작업 시간 초과처럼
작업이 끝까지 완료되지 못한 원칙을 구분합니다. 앞의 경우만
파이프라인을 실패시킵니다. 작업이 실행되지 않은 원칙은 증류할 수 없다고
확인된 것이 아니기 때문입니다. 어느 경우든 원칙은 커밋된 체크섬을 유지하므로
다음 예약 실행이 다시 시도합니다.
관련 문서#
.ai/principles/manifest.yml에 대한 매니페스트 참조.
- 동기화를 구동하는 gem인
gems/gitlab-ai-principles-distiller.