팀원 중 한 명이 한 저장소에서 AGENTS.md 지침을 개선했습니다. 일주일 후, 다른 서비스에는 여전히 이전 규칙이 남아 있습니다. Cursor 설정도 어긋나 있으며, 공유된 Claude 프롬프트는 6개 프로젝트 중 3개에만 복사되었습니다.

이것은 AI 툴링 워크플로우(workflow) 내에 숨겨진 일반적인 구성 관리(configuration-management) 문제입니다. 파일을 수동으로 복사하는 것은 확장성이 떨어지며, 보호된 기본 브랜치(default branches)에 변경 사항을 직접 푸시하는 것도 좋은 해결책이 아닙니다.

이 튜토리얼에서는 team-ai-sync를 사용하여 여러 저장소 간에 AI 에이전트 지침, 프롬프트(prompts), 그리고 에디터 규칙(editor rules)을 일관되게 유지하는 방법을 알아봅니다. 이 워크플로우는 드라이 런(dry-run) 모드로 시작하여, 변경 사항을 일반적인 풀 리퀘스트(pull requests)를 통해 배포하므로 모든 업데이트가 가시적이고 검토 가능하게 유지됩니다.

우리가 구축할 것

우리는 하나의 저장소를 공유 AI 가이드의 신뢰할 수 있는 단일 원천(source of truth)으로 사용할 것입니다. 해당 저장소의 GitHub Actions 워크플로우는 다음을 수행합니다:

1. 버전 관리된 동기화 매니페스트(synchronization manifest)를 읽습니다.
2. 선택된 파일들을 대상 파일들과 비교합니다.
3. 아무것도 작성하지 않고 변경 사항을 미리 봅니다.
4. 드라이 런(dry-run) 검증 후 각 대상 저장소에 풀 리퀘스트(pull request)를 생성하거나 업데이트합니다.

이 접근 방식은 다음과 같은 파일에 유용합니다:

• AGENTS.md 및 CLAUDE.md
• GitHub Copilot 지침 파일
• Cursor 및 Windsurf 규칙
• 재사용 가능한 프롬프트 (reusable prompts)
• 코딩 에이전트를 위한 팀별 문서

이 도구는 숨겨진 모델 컨텍스트(model context)가 아닌 파일을 동기화합니다. AI가 작성했는지 여부를 결정하지 않으며, 비밀 정보(secrets)를 배포하는 용도로 사용해서는 안 됩니다.

사전 요구 사항

다음이 필요합니다:

• 표준 파일(canonical files)을 보유할 GitHub 저장소
• 하나 이상의 대상 저장소
• 해당 대상 저장소에서 브랜치 및 풀 리퀘스트를 생성할 수 있는 권한
• 저장소 간 액세스를 위한 세분화된 개인 액세스 토큰(fine-grained personal access token) 또는 GitHub App 토큰

일반적인 워크플로(workflow)용 GITHUB_TOKEN은 소스 저장소(source repository)를 읽을 수 있습니다. 하지만 저장소 간 쓰기(Cross-repository writes)를 수행하려면 별도의 토큰이 필요합니다. 내장된 토큰은 워크플로가 실행되는 저장소로 범위(scope)가 제한되어 있기 때문입니다.

세분화된 개인 액세스 토큰(fine-grained token)의 경우, 대상 저장소(target repositories)에만 액세스 권한을 부여하십시오. 문서에 명시된 최소 권한은 다음과 같습니다:

• Contents: 읽기 및 쓰기 (read and write)
• Pull requests: 읽기 및 쓰기 (read and write)
• Metadata: 읽기 (read)
• Issues: 워크플로가 라벨(label)을 적용하기를 원하는 경우에만 읽기 및 쓰기 (read and write)

토큰을 저장소(repository) 또는 조직(organization)의 Actions 비밀값(secret)으로 저장하십시오. 이 예시에서는 비밀값의 이름을 TEAM_SYNC_ADMIN_PAT로 지정합니다.

1단계: 표준 파일(canonical files) 생성하기

소스 저장소의 구조가 다음과 같다고 가정해 보겠습니다:

shared-ai-guidance/
├── AGENTS.md
├── prompts/
...