GitHub issue를 작업 계약으로 만드는 AI 주도 개발 템플릿 사용법

서론

이 기사에서는 AI 주도 개발 (AI-driven development)을 수행하기 위해 작성한 템플릿의 구체적인 사용법을 소개합니다.

설계 사상이나, 바이브 코딩 (Vibe Coding)과 AI 주도 개발의 차이점에 대해서는 사상 편에 정리해 두었습니다.

템플릿 리포지토리는 여기입니다.

이 템플릿은 GitHub issue를 개발의 최소 단위로 취급하며, AI 에이전트와 인간이 동일한 전제를 읽고 작업하기 위한 틀입니다.

AI에게 "적당히 구현해 줘"라고 의뢰하는 것이 아니라, issue 본문, 관련 문서, 수락 조건 (Acceptance Criteria)을 작업 계약으로서 취급합니다.

특정 AI 코딩 도구의 스킬 기능은 필수 전제로 두지 않았습니다.

템플릿을 복사하면 리포지토리 내의 문서, Issue Form, PR 템플릿, GitHub Actions를 사용하여 바로 개발을 시작할 수 있다는 점을 중시하고 있습니다.

템플릿의 목적

이번에 만든 템플릿은 AI에게 무엇을 읽히고, 무엇을 지키게 하며, 어떤 단위로 작업하게 하고, 어떻게 검증할지를 리포지토리 구조로서 정의하기 위한 것입니다.

주요 목적은 다음과 같습니다.

바이브 코딩 (Vibe Coding)과는 다른 AI 주도 개발을 실행할 수 있도록 함
개인 개발에서도 팀 개발에서도 사용할 수 있는 운용 규칙을 마련함
issue를 작업 계약으로 취급할 수 있도록 함
요구사항, 설계, API, 테스트, 운용 규칙을 Everything as Code로서 관리함
Codex, Claude Code, 기타 AI 개발 도구에서도 동일한 전제를 공유할 수 있도록 함
복수의 AI 에이전트로 작업할 경우의 담당 범위를 명확히 함

파일 구성

주요 파일 구성은 다음과 같습니다.

.
├── AGENTS.md
├── CLAUDE.md
...

AGENTS.md

AGENTS.md는 AI 에이전트 공통 입구입니다.

이 리포지토리에서 작업하는 AI에 대해, 가장 먼저 읽어야 할 파일, issue를 기점으로 작업할 것, 담당이 설정되지 않은 issue에는 착수하지 말 것, 구현 전에 요구사항이나 설계를 확인할 것 등을 전달합니다.

Codex와 같이 AGENTS.md를 읽는 도구에서는 그대로 입구로 사용할 수 있습니다.

CLAUDE.md

CLAUDE.md는 Claude Code를 위한 입구입니다.

도구마다 읽어들이는 파일명이 다르기 때문에, Claude Code에서는 CLAUDE.md에서 공통 규칙으로 유도하는 구성으로 만들었습니다.

규칙 본체는 가능한 한 AGENTS.md 및 docs/common/development-rules.md와 일치하도록 맞추었습니다.

docs/common/development-rules.md

AI를 위한 개발 규약입니다.

issue를 개발의 최소 단위로 취급할 것, 구현 전에 요구사항·설계·API 정의·테스트 관점을 확인할 것, TDD를 전제로 할 것, API나 Infrastructure 변경 시의 주의사항 등을 정의하고 있습니다.

이 템플릿 내에서 AI에게 읽히는 가장 중요한 문서입니다.

docs/common/operations-manual.md

인간을 위한 운용 절차입니다.

issue를 만드는 방법, AI에게 의뢰하는 방법, GitHub 리포지토리 생성 타이밍, 멀티 에이전트 이용 시의 확인 사항 등을 정리해 두었습니다.

기존 프로젝트에 도입할 경우의 조사 절차나, 변경 리스크에 따라 공정을 가볍게 하거나 무겁게 하는 운용 방식도 여기에 정리되어 있습니다.

docs/common/quality-gates.md

NFR, Security, Resiliency의 품질 게이트 (Quality Gates)입니다.

AI가 만든 것을 "기능으로서 동작함"에서 끝내지 않고, 비기능 요구사항 (NFR), 보안 (Security), 장애 시의 동작까지 확인하기 위해 마련했습니다.

모든 issue에서 모든 항목을 충족할 필요는 없습니다.

AI는 변경 내용에 따라 NFR / Security / Resiliency의 해당 여부, 확인 결과, 미확인 사항을 정리합니다.

특히 인증, 인가, Infrastructure, 외부 연동, 운영 데이터, 개인정보에 영향을 미치는 변경에서는 이 품질 게이트를 구현 전에 확인합니다.

docs/architecture.md

이용 대상 프로젝트의 채택 아키텍처를 기록하는 파일입니다.

템플릿에서는 기본 구성을 정의하고 있지만, 실제 프로젝트에서 다른 구성을 채택하는 경우에는 이 파일에 이유와 영향 범위를 남깁니다.

아키텍처 (Architecture), 공통 정의, API, 인증 (Authentication), 인프라스트럭처 (Infrastructure)에 영향을 미치는 변경은 AI만으로 진행하지 않고, 사람이 판단한다는 전제입니다.

docs/prototype.md

영업 데모, 요구사항 확인, 화면 전환 확인, 기술 검증을 위해 프로토타입을 만드는 경우의 기록 장소입니다.

프로토타입은 본 작업 구현이 아니라, 얻은 지식을 요구사항 정의나 설계로 되돌리기 위한 것으로 취급합니다.

프로토타입을 만든 경우에는 목적, 재현 범위, 재현하지 않는 범위, 본산 아키텍처와의 차이점, 검증 결과, 후속 issue 후보를 기록합니다.

GitHub Issue Form

.github/ISSUE_TEMPLATE/feature.yml에는 issue 생성 시의 입력 항목을 정의하고 있습니다.

목적, 스코프 (Scope), 비스코프 (Non-scope), 수락 조건 (Acceptance Criteria), 테스트 관점 등을 입력하는 형식으로 만들어, AI가 작업 계약 (Work Contract)으로서 읽을 수 있는 issue를 만들기 쉽게 구성했습니다.

AI에게 의뢰하는 issue에서는 최소한 다음 정보를 명확히 합니다.

목적
배경
변경 리스크 (Change Risk)
스코프 (Scope)
비스코프 (Non-scope)
수락 조건 (Acceptance Criteria)
영향 범위
테스트 관점
Quality Gates
관련 문서
미결 사항

이는 issue를 단순한 태스크명이 아니라, AI와 사람이 공유하는 작업 계약 (Work Contract)으로 취급하기 위해서입니다.

GitHub Actions

GitHub Actions에서는 주로 다음 사항을 체크합니다.

issue 본문에 필요한 항목이 갖춰져 있는지
조건을 만족하는 issue에 ready-for-ai 라벨을 붙이는지
부족한 부분이 있는 issue에 needs-info 라벨을 붙이는지
PR 본문에 Closes #123 형식의 대응 issue가 포함되어 있는지
PR 본문에 검증 결과가 포함되어 있는지

AI에게 작업을 의뢰할 수 있는 상태인지 여부를 라벨과 체크를 통해 가시화하기 위함입니다.

ready-for-ai는 AI에게 의뢰할 수 있는 상태임을 나타내는 라벨입니다. 자동 착수나 담당자 확정을 의미하는 것은 아닙니다.

변경 리스크로 공정을 조정하기

AI 주도 개발 (AI-Driven Development)에서는 모든 변경을 동일한 무게로 다루면 운영 부담이 커집니다.

따라서 이 템플릿에서는 issue마다 변경 리스크를 Low Risk, Medium Risk, High Risk로 분류합니다.

Low Risk

문구 수정, README 수정, 작은 문서 수정, 테스트 추가만 수행하는 경우, 명확하고 경미한 버그 수정 등이 해당합니다.

이 경우에는 issue별 요구사항 정의서나 설계서를 생략하고, 수락 조건과 영향 범위를 확인한 후 최소한의 차이(diff)로 진행합니다.

Medium Risk

통상적인 기능 추가, 기존 화면이나 기존 API를 사용하는 변경, 인증된 사용자를 위한 표준적인 기능 등이 해당합니다.

요구사항, 설계, 테스트 관점을 정리하고, 구현 전에 사람이 방침을 확인한 후 진행합니다.

High Risk

인증 (Authentication), 인가 (Authorization), API 사양, 공통 데이터 모델, DB, 인프라스트럭처 (Infrastructure), 외부 서비스 연동, 결제, 알림, 운영 데이터, 개인정보, 보안 (Security), 레질리언스 (Resilience)에 영향을 미치는 변경입니다.

이 경우에는 docs/system-context.md나 docs/architecture.md를 확인하고, 필요에 따라 요구사항·설계·API 정의를 업데이트하며, Quality Gates 확인 및 사람의 명시적 승인을 거친 후에 구현합니다.

가벼운 변경은 가볍게, 위험한 변경은 두텁게 다룸으로써 템플릿이 형식적인 의식(Ritual)이 되지 않도록 합니다.

기존 프로젝트에 도입하는 경우

기존 코드베이스에 이 템플릿을 도입할 때는 AI에게 갑자기 기능 구현이나 리팩터링 (Refactoring)을 의뢰하지 않습니다.

먼저 조사 전용 issue를 만들어 AI가 기존 구성을 리버스 엔지니어링 (Reverse Engineering)하게 합니다.

조사할 내용은 예를 들어 다음과 같습니다.

디렉터리 구성과 주요 책임
기술 스택 (Tech Stack)
실행, 빌드, 테스트, 배포 방법
Frontend, Backend, Infrastructure, Auth, Data Store, External Services의 현황
API, 인증/인가, 데이터 모델, 환경 변수, 시크릿 (Secret), 배포 전제 조건
기존 문서와 부족한 문서
docs/system-context.md와 docs/architecture.md의 작성 또는 업데이트 안
후속 issue 후보

이 조사 issue에서는 코드 변경, 의존성 업데이트, API 사양 변경, 인프라스트럭처 (Infrastructure) 변경을 수행하지 않습니다.

기존 코드의 전제를 이해하기 전에 AI에게 변경을 시키면, 암묵적인 구성이나 운용 전제를 깨뜨리기 쉽기 때문입니다.

기본 개발 플로우

이 템플릿에서 상정하고 있는 흐름은 다음과 같습니다.

GitHub issue를 작성한다
issue에 목적, 스코프 (Scope), 비 스코프 (Non-scope), 수락 조건 (Acceptance Criteria), 테스트 관점을 작성한다
ready-for-ai 라벨이 붙은 상태로 만든다 - issue에 담당자를 설정한다
AI에게 issue 번호를 전달한다
AI가 AGENTS.md, 관련 문서, issue 본문을 읽는다 - AI가 목적, 수락 조건, 영향 범위, 변경 리스크, 불명확한 점을 요약한다
필요하다면 요구사항 정의, 설계, API 사양을 먼저 업데이트한다
Quality Gates의 해당 여부를 확인한다
테스트를 작성한 후 구현한다
PR에 대응 issue, 검증 결과, Quality Gates, 잔여 과제를 작성한다

포인트는 AI에게 갑자기 구현을 시키지 않는 것입니다.

먼저 AI에게 전제를 읽게 하고, 작업 범위와 불명확한 점을 도출하게 합니다.

그 후에 사람이 문제없다고 판단하면 구현으로 진행합니다.

AI에게 요청하는 예시

예를 들어, Codex나 Claude Code에는 다음과 같이 요청합니다.

issue #123에 착수합니다.
AGENTS.md, docs/common/development-rules.md, docs/system-context.md, docs/architecture.md, docs/prototype.md, issue 본문을 읽고,
목적, 수락 조건, 영향 범위, 변경 리스크 분류, Quality Gates의 해당 여부, 불명확한 점, 구현 전에 업데이트해야 할 문서를 보고해 주세요.
...

이 요청에서는 AI에게 처음부터 구현을 시키지 않습니다.

먼저 읽어야 할 파일을 지정하고, 요약과 불명확한 점에 대한 보고를 요구하고 있습니다.

AI 코딩 도구의 스킬 (Skill)을 사용할 때도, 이 흐름을 대체하는 것이 아니라 보조로서 다루는 것이 좋다고 생각합니다.

예를 들어, issue 작성, PR 본문 생성, 정형적인 체크리스트 작성과 같은 반복 작업은 스킬화하기 쉬운 영역입니다.

반면, 요구사항, 설계, 수락 조건, 공정 관리, 권한 및 금지 사항과 같은 핵심 규칙은 스킬이 아니라 리포지토리 (Repository) 내의 문서로 남기는 방침입니다.

팀 개발에서 의식하고 있는 점

AI 주도 개발 이야기는 개인 개발의 맥락에서 이야기되는 경우가 많습니다.

하지만 실제로는 팀에서 사용할 때야말로 규칙이 중요해집니다.

이 템플릿에서는 다음과 같은 점을 명확히 하고 있습니다.

issue 외의 변경을 시키지 않는다
담당자가 설정되지 않은 issue에는 착수시키지 않는다
ready-for-ai는 AI에게 의뢰할 수 있는 상태임을 나타낼 뿐, 자동 착수를 의미하지 않는다
여러 AI 에이전트 (Agent)를 사용하는 경우에는 primary agent 또는 통합 담당자를 결정한다
각 에이전트의 담당 범위와 변경 가능한 파일을 결정한다
PR 본문에 대응 issue, 수락 조건별 대응, 검증 결과, 잔여 과제를 남긴다
High Risk 변경에서는 NFR / Security / Resiliency의 Quality Gates를 확인한다

AI 에이전트를 여러 개 사용하는 것 자체가 목적은 아닙니다.

중요한 것은 사람과 AI를 포함한 팀 전체가 누가 무엇을 근거로 어디까지 변경해도 되는지를 명확히 하는 것입니다.

이 템플릿이 적합한 케이스

이 템플릿은 다음과 같은 개발에 적합합니다.

GitHub issue와 PR을 중심으로 개발하고 있다
AI에게 구현을 맡기고 싶지만, 멋대로 사양을 추가하는 것은 피하고 싶다
요구사항, 설계, 테스트 관점을 대화 로그가 아닌 리포지토리에 남기고 싶다
Codex, Claude Code, 기타 AI 개발 도구를 팀에서 병용하고 싶다
클라우드, 인증, 외부 연동을 포함하는 애플리케이션을 개발하고 싶다
여러 명 또는 여러 AI 에이전트로 변경 범위를 관리하고 싶다
프로토타입과 본 프로덕션 구현을 나누어 다루고 싶다

반대로, 개인의 작은 시작품으로 issue나 PR을 사용하지 않고 한 번에 만들고 싶은 경우에는 조금 무겁습니다.

그 경우에도 AGENTS.md와 docs/common/development-rules.md의 일부만 도입하여 사용하는 방식은 가능합니다.

도입 시의 흐름

새로운 프로젝트에서 사용하는 경우는 다음과 같은 흐름을 상정하고 있습니다.

템플릿으로부터 리포지토리를 생성한다
README.md

프로젝트용으로 업데이트한다 - GitHub Issues와 GitHub Actions를 활성화한다

docs/system-context.md를 생성하여 앱 전체의 전제 조건을 작성한다
docs/architecture.md를 업데이트하여 채택할 아키텍처를 결정한다
기능 단위로 나누어 issue를 생성한다
issue마다 변경 리스크와 Quality Gates 해당 여부를 정리한다
ready-for-ai 라벨과 담당자를 확인한 후 AI에게 요청한다

docs/system-context.md는 템플릿에 처음부터 고정 파일로 포함되어 있지 않습니다.

사용할 프로젝트마다 앱의 목적, 대상 사용자, 기능 목록, 용어, 공통 규칙을 만드는 것을 상정하고 있습니다.

요약

이 템플릿은 AI에게 무엇을 읽히고, 무엇을 준수하게 하며, 어떤 단위로 작업하게 하고, 어떻게 검증할지를 리포지토리에 고정하기 위한 것입니다.

issue를 작업 계약으로 만들고, AGENTS.md, 개발 규약, 운영 매뉴얼, Issue Form, PR 템플릿, GitHub Actions를 조합함으로써 AI 주도 개발 (AI-driven development)을 팀에서도 다루기 쉬운 형태로 만듭니다.

우선 작은 issue부터 사용하기 시작하여, AI에게 전제 조건을 읽히고 요약과 불명확한 점을 도출하게 하는 것부터 시도해 보는 것이 좋다고 생각합니다.