원칙 동기화는 .ai/principles/manifest.yml 을 읽어 어떤 원칙을 생성할지, 각 원칙이 어떤 소스 파일에서 파생되는지, 자동 생성 머지 리퀘스트를 어떻게 열지 결정합니다.

온보딩 흐름은 AI 개발 원칙을 참고합니다.

최상위 키#

원칙 항목#

principles: 아래의 각 키는 슬러그입니다. 값은 다음 키를 가진 맵입니다.

소스 항목#

sources:의 각 항목은 다음 키를 가진 맵입니다.

자동 머지 리퀘스트 설정#

auto_mr: 맵은 예약된 동기화가 머지 리퀘스트를 여는 방식을 제어합니다.

머지 리퀘스트 리뷰어#

팀별 머지 리퀘스트는 해당 원칙을 마지막으로 디스틸한 이후 소스 문서를 변경한 사람에게 핑을 보냅니다. 동기화는 이전 디스틸 시점과 대상 브랜치 사이 구간의 커밋 작성자를 GitLab GraphQL API로 조회하고, 연결된 GitLab 사용자를 머지 리퀘스트 요약에서 멘션합니다. 이는 공개 이메일뿐 아니라 계정에 연결된 모든 확인된 이메일을 기준으로 대조합니다. 디스틸러는 선언된 모든 SSOT 경로에 걸쳐 기여자별 최신 커밋을 유지하고 그 날짜로 기여자의 순위를 매긴 다음, 최대 4명의 리뷰어를 선정합니다. 동기화는 봇 계정, 알려진 서비스 계정의 소규모 거부 목록에 해당하는 작성자, 커밋 이메일이 어떤 GitLab 계정에도 연결되지 않은 작성자를 건너뜁니다.

어떤 작성자도 사용자로 확인되지 않으면 요약은 owner_team에 대한 fallback_ping_team 동작으로 대체됩니다. 승인은 항상 CODEOWNERS를 통해 owner_team으로 라우팅되므로, 연락이 닿지 않는 작성자 때문에 머지 리퀘스트가 막히는 일은 없습니다.

정적 항목#

static_entries: 아래에 나열된 파일은 에이전트 컨텍스트 로딩 스킬에서 참조하지만 동기화가 생성하지는 않습니다. 소스 문서에서 파생되지 않고 .ai/ 아래에서 수작업으로 관리하는 주제별 모듈에 이 목록을 사용합니다.

예시#

최소 원칙 항목#

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/

모든 필드를 포함한 원칙 항목#

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_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_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 를 참고합니다.