AI 에이전트와 함께 일하는 팀의 GitHub 구조

읽는 쪽: 개발자, 리뷰어(CODEOWNER), Claude Code, GitHub Copilot, Cursor, OpenAI Codex, Gemini CLI, Aider · Zed · Jules

1. 1

   규칙AI에 대한 지시. 강제력 없음

   팀 규칙은 AGENTS.md 한 곳에 씁니다. 도구별 파일은 이 파일을 가리키기만 하고, 특정 파일을 수정할 때만 경로별 규칙이 더해집니다.

   AGENTS.md · CLAUDE.md · copilot-instructions.md · .cursor/rules · GEMINI.md · REVIEW.md
2. 2

   로컬 가드레일개발자 PC

   훅이 비밀·정책 파일 수정, main 커밋, 강제 푸시를 막고 수정 직후 포맷과 글·화면 검사를 실행합니다. pre-commit이 사람의 커밋에도 같은 검사를 적용합니다.

   plugins/team-ai-workflow · .claude/settings.json · .pre-commit-config.yaml
3. 3

   GitHub 거버넌스서버

   어떤 도구로 만든 코드든 PR, CODEOWNER 승인, ci-ok를 통과해야 main에 들어갑니다. 보안 스캔도 서버에서 실행됩니다.

   scripts/rulesets/main.json · .github/CODEOWNERS · .github/ISSUE_TEMPLATE/
4. 4

   이슈에서 머지까지워크플로 22개

   분류, 구현, 초안 PR, 리뷰, 릴리스를 워크플로와 AI 에이전트가 진행합니다. 사람은 두 번 판단합니다.

   ai:ready 부여CODEOWNER 승인
5. 5

   AI 실행 주체선택 사항

   기본은 내 자리에서 내 claude 로그인으로 실행합니다. 서버 자동화가 필요하면 사내 로컬 LLM이나 Anthropic을 고릅니다.

6. 6

   여러 레포 배포허브 1개, 서비스 레포 N개

   처음에는 템플릿을 복사하고, 이후에는 플러그인 갱신으로 훅과 스킬을 모든 레포에 맞춥니다.

AGENTS.md

AI 코딩 도구들이 공통으로 읽는 에이전트용 README. 공개 형식이며 이 레포의 팀 규칙이 모두 이 파일에 있습니다.

에이전트

지시를 받아 파일을 읽고 수정하고 명령을 실행하는 AI. 이 템플릿에서는 이슈를 받아 코드를 작성하고 PR을 엽니다.

훅(hook)

AI가 행동하기 직전이나 직후에 자동으로 실행되는 스크립트. AI가 무시할 수 없습니다. 예: .env 수정 차단

스킬(skill)

반복 작업의 절차서. /implement-issue 12처럼 호출하거나 상황에 맞으면 AI가 스스로 불러옵니다.

서브에이전트

한 가지 역할만 맡는 별도 AI. 작업한 AI와 독립된 관점으로 검토할 때 씁니다. 예: security-reviewer

플러그인 · 마켓플레이스

훅·스킬·서브에이전트를 묶은 패키지와 그 목록. 이 레포 자체가 마켓플레이스 "ai-collab"입니다.

워크플로

이슈 생성, PR, 푸시 같은 이벤트에 GitHub Actions가 자동으로 실행하는 작업. .github/workflows/

룰셋 · CODEOWNERS

룰셋은 브랜치 보호 규칙, CODEOWNERS는 경로별 책임 리뷰어 목록입니다.

라벨 상태

이슈의 진행 단계를 라벨로 표시하는 방식. 워크플로가 라벨을 보고 실행됩니다.

claude -p

대화창 없이 명령 한 줄로 Claude Code를 실행하는 방식. make ai-*가 내부에서 사용합니다.

ci-ok

린트·타입·테스트 결과를 하나로 모은 검사. 머지 조건으로 지정합니다.

squash 머지

PR의 커밋을 하나로 합쳐 반영하는 방식. PR 제목이 main의 커밋 제목이 됩니다.

sequenceDiagram
  autonumber
  actor Dev as 팀원
  participant GH as GitHub
  participant AI as AI 에이전트
  participant CI as CI · 검사
  actor Rev as 리뷰어(CODEOWNER)
  Dev->>GH: 이슈 #35;42 등록 (양식)
  GH->>AI: 이슈 생성 이벤트
  AI-->>GH: 라벨 제안 + 빠진 정보 댓글
  Dev->>GH: 보강 후 ai:ready 라벨
  GH->>AI: ai:ready 이벤트
  AI->>AI: 테스트 먼저 → 구현 → make check
  AI-->>GH: 커밋 + 초안 PR (ai:generated)
  GH->>CI: ci-ok · 제목 · 크기 · AI 공개 · 보안
  AI-->>GH: 줄 단위 리뷰 (승인 아님)
  Rev->>GH: 코드 리뷰 → 승인
  GH-->>GH: squash 머지 · 이슈 ai:done · 릴리스 노트

1. 이슈 등록

   팀원이 "작업(AI 가능)" 양식으로 #42를 작성합니다. 수용 기준은 "같은 IP에서 1분에 5회 넘게 로그인하면 429 응답", 범위는 src/auth/입니다.

2. AI 분류

   AI가 type/feature, area/auth, priority/p2, size/S 라벨을 추가하고 "실패 시 응답 본문 형식이 없다"는 댓글을 남깁니다. 이슈를 닫거나 담당자를 바꾸지 않습니다.

3. AI 위임 결정

   메인테이너가 빠진 내용을 보강하고 ai:ready 라벨을 붙입니다. 쓰기 권한이 있는 사람만 붙일 수 있습니다. 보안·개인정보·운영 장애 이슈에는 붙이지 않습니다.

   사람

4. AI 구현

   라벨이 ai:in-progress로 바뀝니다. AI가 별도 작업 폴더(worktree)의 ai/issue-42-… 브랜치에서 수용 기준을 테스트로 먼저 작성하고 구현합니다. make check가 통과해야 커밋합니다.

5. 초안 PR

   "Closes #42"가 들어간 초안 PR이 ai:generated 라벨로 열리고 이슈는 ai:review가 됩니다. 실패하면 이슈가 ai:needs-human이 되고 이유가 댓글로 남습니다.

6. 자동 검사와 AI 리뷰

   CI(ci-ok), PR 제목·크기·AI 공개 검사, 보안 스캔이 실행됩니다. AI 리뷰어는 "1분 경계에서 카운터가 초기화되지 않음" 같은 지적을 줄 단위로 남깁니다. AI 리뷰는 승인으로 집계하지 않습니다.

7. 사람 리뷰와 승인

   CODEOWNER가 코드를 읽고 타당한 AI 지적의 반영을 요청한 뒤 승인합니다. 승인 후 새 커밋이 생기면 다시 승인해야 합니다. AI 커밋이 있는 PR은 별도의 사람 승인 검사도 통과해야 합니다.

   사람

8. 머지와 릴리스

   squash 머지로 PR 제목 "feat(auth): add login rate limit (#42)"가 main의 커밋 제목이 됩니다. 이슈는 ai:done이 되고 release-please가 다음 버전의 변경 기록에 추가합니다.

라벨로 보는 이슈 상태

위 단계에서 이슈 라벨이 바뀝니다. 이슈 목록의 라벨만 보면 누가 무엇을 기다리는지 알 수 있습니다.

flowchart LR
  R["요청 / 아이디어"] --> S{"한 문장으로
설명 가능?"}
  S -- 예 --> T0["T0: 바로 브랜치"]
  S -- 아니오 --> M{"여러 모듈·레포 또는
영역이 모호?"}
  M -- 아니오 --> T1["T1: 계획을 PR 본문에"]
  M -- 예 --> T2["T2: /design → 설계 PR"]
  T0 & T1 & T2 --> O["겹침 확인"]
  O -- 겹침 --> TALK["담당자와 협의
합치기 · 영역 나누기"]
  O -- 없음 --> W["구현 PR (설계 링크)"]

겹침 확인

설계 머리말의 areas에 변경할 경로(src/auth/**)나 이름 붙은 영역(api:/login, db:users)을 적습니다. 허브의 work-board.yml이 30분마다 등록된 모든 레포의 활성 설계와 열린 PR의 변경 파일을 board.json으로 모읍니다. 스크립트로 처리하므로 토큰을 쓰지 않습니다. AI는 세션을 시작할 때 영역별 담당자 요약(약 2천 토큰)을 받습니다. 작업 전에는 /check-overlap으로 보드와 비교합니다. 사람은 같은 확인을 명령으로 실행합니다.

PR마다 design-check.yml이 겹침을 댓글로 알리지만 머지를 막지는 않습니다. 보드는 담당자끼리 협의할 시점을 알릴 뿐이며 협의를 대신하지 않습니다.

규칙: AGENTS.md 하나

팀원마다 AI 도구가 다릅니다. 도구마다 규칙 파일을 따로 두면 몇 주 만에 내용이 어긋납니다. 그래서 규칙은 AGENTS.md 한 곳에 쓰고 도구별 파일에는 AGENTS.md를 가리키는 줄만 둡니다.

강제 장치

막혔을 때

아래 차단은 의도된 동작입니다. 정당한 변경이면 사람이 직접 수정하고 PR에 이유를 적습니다.

장치를 최소로 두는 이유

최신 모델은 지시를 강하게 따릅니다. 이전 모델에 맞춰 쌓은 "반드시·절대" 규칙과 잦은 확인은 오히려 과잉 반응과 확인 피로를 만듭니다. 그래서 사고 비용이 큰 항목만 결정적으로 막고 나머지는 덜어냈습니다. 모델을 바꿀 때마다 "이 줄을 지우면 실수하는가"를 다시 점검합니다(docs/15-lean-harness.md).

flowchart TD
  Q1{"이벤트 발생 시
AI 자동 반응 필요?"}
  Q1 -- 아니오 --> A["내 자리에서 실행
내 claude 로그인 · 설정 없음
사람이 명령할 때만"]
  Q1 -- 예 --> Q2{"코드의 외부 전송
금지?"}
  Q2 -- 예 --> B["사내 로컬 LLM
llama.cpp 또는 Ollama + 자체 러너
AI_BACKEND=local · 품질은 모델에 따라 다름"]
  Q2 -- 아니오 --> C["Anthropic
구독 토큰 또는 API 키
AI_BACKEND=anthropic"]

내 자리에서 실행할 때는 아래 명령을 씁니다. POST=1을 붙일 때만 결과를 GitHub에 기록합니다. 서버 설정은 docs/13-ai-backends.md와 infra/local-llm/README.md에 있습니다.

make ai-triage ISSUE=42            # 분류 결과만 화면에 출력
make ai-triage ISSUE=42 POST=1     # 라벨 적용과 댓글
make ai-review PR=57 POST=1        # 리뷰 댓글 (승인하지 않음)
make ai-implement ISSUE=42 POST=1  # 별도 폴더에서 구현 후 초안 PR
make ai-queue POST=1               # ai:ready 이슈를 차례로 처리

flowchart LR
  subgraph HUB["허브 (이 레포)"]
    T["템플릿 파일
규칙 · 양식 · 워크플로"]
    M["플러그인 마켓플레이스
훅 · 스킬 · 서브에이전트"]
  end
  subgraph ORG["조직 설정 (선택)"]
    W["재사용 워크플로 · 조직 룰셋"]
  end
  S1["svc-payments"]
  S2["svc-auth"]
  S3["web"]
  T -- "make new-repo (처음 1회 복사)" --> S1 & S2 & S3
  M -- "plugin update (계속 갱신)" --> S1 & S2 & S3
  W -.-> S1 & S2 & S3

AI는 현재 레포 밖의 파일을 볼 수 없습니다. 여러 레포에 걸친 변경은 T2 설계 하나의 repos에 모든 레포를 적고 구현은 레포별 이슈로 나눕니다. 다른 레포를 함께 참고해야 하면 Claude Code에 --add-dir ../다른레포로 폴더를 추가합니다. 여러 AI를 동시에 돌릴 때는 AI마다 다른 파일을 맡기고 worktree로 작업 폴더를 나눕니다.

코드 리뷰는 없어지지 않고 앞 단계로 옮겨갑니다. 의도(설계·계약), 검증(테스트·계약 diff·평가), 위험 구간의 표본 리뷰가 대상입니다(docs/16-team-scale-ai.md).

스킬은 모델이 필요하다고 판단할 때만 로드되므로 항상 쓰인다는 보장이 없습니다. 대신 기계로 판별할 수 있는 위반은 수정 직후 훅, pre-commit, CI가 같은 규칙으로 검사합니다(강제 장치 표의 포맷·스타일 훅과 pre-commit). 훅이 위반을 돌려주면 AI가 그 자리에서 고치므로 스킬을 부르지 않은 작업에도 기준이 적용됩니다.

두 스킬과 검사 규칙, 디자인 시스템의 원본은 다른 프로젝트에서도 쓸 수 있도록 별도 레포 jungrok5/ai-design에 있습니다. 이 레포는 마켓플레이스에 고정한 커밋 하나를 쓰고, team-ai-workflow를 설치하면 ai-design 플러그인이 의존성으로 함께 설치됩니다.

팀 스킬 추가

스킬은 개인, 커뮤니티, 팀 세 등급으로 추가합니다. 명령 하나가 등급에 맞는 뼈대와 평가 케이스를 만들고, 형식·버전·평가는 CI가 확인합니다(docs/18-adding-skills.md).

make new-skill NAME=x TIER=community DESC="..."
make ai-eval     # 호출해야 할 때와 하지 않아야 할 때를 함께 평가