AI 개발 원칙

GitLab이 doc/development/ 문서에서 AI 에이전트용 원칙 파일을 생성하고 동기화하는 방법을 설명합니다.

GitLab은 doc/development/ 에 있는 개발 관례를 AI 에이전트가 변경 사항을 계획하거나 구현할 때 로드하는 원칙 파일로 추출합니다. 그 결과로 생성된 코드는 사람 리뷰어가 기대하는 관례를 따릅니다. 이 페이지는 팀이 doc/development/ 에 문서를 관리하고 있으며 해당 문서에서 AI 원칙을 추출하려는 경우에 사용하세요. 운영 런북(CI 변수, 서비스 계정 인증, 스케줄 복구)은 리포지터리 내 .ai/principles/README.md 를 참조하세요. 동기화 작동 방식 # gitlab-org/gitlab 의 예약된 CI job이 매주 실행되며 다음 단계를 수행합니다: .ai/principles/manifest.yml 을 읽어 각 원칙이 어떤 문서 파일에서 파생되었는지 확인합니다. 각 원칙의 매니페스트 항목, 기준선(baseline), 소스 파일에 대한 체크섬 비교 를 통해 드리프트를 감지합니다. 이를 기존 추출 파일의 front matter에 저장된 체크섬과 비교합니다. 드리프트가 발생한 각 원칙마다 job 하나씩을 갖는 하위 파이프라인을 생성합니다. 각 job에서 GitLab Duo Agent Platform Workflow API를 호출하여 현재 소스 문서를 기반으로 해당 원칙의 추출 파일을 재생성합니다. 해당 job들에서 재생성된 파일을 수집하여 .ai/principles/distilled/ 에 씁니다. 파일이 변경된 경우 머지 리퀘스트를 엽니다. 해당 머지 리퀘스트는 기본 브랜치를 타깃으로 하며 병합 전 사람의 승인이 필요합니다. 각 원칙을 자체 job에서 추출하면 각각 고유한 타임아웃을 갖게 되므로, 느린 원칙 하나가 실행 결과 전체를 폐기하지 않습니다. 추출은 서버 측에서 실행됩니다. 에이전트는 동기화가 실행되는 브랜치(주간 스케줄의 경우 기본 브랜치)에서 소스 파일을 읽습니다. 동기화를 구동하는 스크립트는 gitlab-ai-principles-distiller gem입니다. 전체 흐름의 다이어그램은 AI 원칙 추출 흐름 을 참조하세요. 원칙 그룹 추가 # 팀이 doc/development/ 아래의 문서를 소유하고 있으며 해당 문서에서 추출된 원칙을 생성하려는 경우 이 절차를 사용하세요. 원칙 그룹(예: Database, Frontend, Testing)은 일반적으로 매니페스트 내에서 group: 라벨을 공유하는 여러 관련 원칙을 포함합니다. 그룹의 각 원칙은 하나의 추출 파일이 됩니다. 다음의 경우 그룹을 여러 원칙으로 분리하세요: 소스 문서가 너무 커서 추출 파일을 한 번에 훑어보기 어려운 경우. 서로 다른 원칙이 서로 다른 리포지터리 경로에 적용되며 별도의 file_filters: 가 유용한 경우. 예를 들어, Database 그룹은 database-fundamentals , database-migrations , database-schema , database-queries 를 포함합니다. 각 원칙의 소스 파일을 식별하세요. 각 소스 파일은 다음을 충족해야 합니다: doc/development