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에 저장된 체크섬과 비교합니다. 드리프트가 발생한 각 원칙에 대해 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를 사용하고 같은 그룹의 원칙에는 공통