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 을 읽어 각 원칙이 어떤 문서 파일에서 파생되는지 확인합니다. 각 원칙의 매니페스트 항목, 기준선, 소스 파일에 대한 체크섬을 비교 해, 기존 추출 파일의 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/ 아래에 있어야