AI가 엇나가지 않게: 바로 적용 가능한 협업 엔지니어링 방법 (템플릿 포함)

• AI에게 버그를 고쳐 달라고 했더니, 상관없는 코드까지 손대서 결국 수동으로 되돌렸다
• 프롬프트를 잔뜩 써도 올바른 파일을 못 찾고, 결국 “찍어서” 수정한다
• 대화가 길어지면 제약을 잊기 시작하고 품질이 급격히 떨어진다

• AGENTS.md: 저장소 레벨의 하드 제약(레드라인, 기본값, Done 정의)
• docs/ai-playbook/index.md: 1페이지 인덱스(고신호 진입점)
• docs/ai-playbook/code-map.md: 코드 맵(어디를 고칠지)
• docs/ai-playbook/flows.md: 핵심 플로우(어떻게 동작하는지)
• docs/ai-playbook/collab-rules.md: 협업 규칙 + 변경 계획 템플릿(어떻게 일할지)

Step 0: 경계와 Done을 먼저 정의하기 (프롬프트부터 시작하지 말기)

1. Boundary(경계): 절대 하면 안 되는 것(프라이버시/아키텍처 레드라인, 프로토콜 호환, 핵심 파라미터 가드레일)
2. Scope(범위): 한 번에 한 목표. “겸사겸사” 금지
3. Done(완료): 빌드/테스트/수동 회귀 체크리스트를 반드시 작성

목표는 하나, 먼저 계획; 프라이버시/아키텍처 레드라인을 넘지 말 것; Done은 빌드 통과 + 회귀 체크리스트 포함.

흔한 안티패턴

1. 계획 없이 “코드 고쳐줘”부터 시작
   • 결과: 10개 파일을 고친 뒤 방향이 틀렸다는 걸 깨닫고, 롤백 비용이 급격히 커진다
   • 더 나은 방법: 먼저 변경 계획을 요구하고, 승인 후에만 구현한다
2. 문서를 전부 프롬프트에 던지기(문맥 과부하)
   • 결과: 문맥이 과부하되어 신호를 못 보고(엔트리 포인트조차 못 찾고) 결국 “찍어서” 고친다
   • 더 나은 방법: 고신호 인덱스 + 코드 맵으로 길을 먼저 잡는다
3. “겸사겸사 최적화” 허용
   • 결과: 한 PR에 여러 목표가 섞여 리뷰 비용이 폭증하고, 버그가 나면 되돌리기도 더 어려워진다
   • 더 나은 방법: single-scope로 작게 쪼개서, 쉽게 되돌릴 수 있게 만든다

Step 1: AGENTS.md 쓰기 (하드 제약을 반복 적용)

• Plan first: AGENTS.en.md:7
• One change, one purpose: AGENTS.en.md:8
• Privacy & architecture red line: AGENTS.en.md:9
• Docs must stay in sync: AGENTS.en.md:12
• Verification required: AGENTS.en.md:13

# AGENTS — Repo Rules

First Principles

- Plan-first: Propose a change plan and get approval before writing code
- Single-scope: One PR solves one goal; avoid “while I’m here” fixes
- Redlines: Never cross privacy/architecture/protocol/key-parameter guardrails
- Docs-sync: Keep the playbook docs in sync when entry points/flows/interfaces change
- Validation: Must include build/tests and key manual regression checklist

다국어 지원

• AGENTS.en.md를 canonical(기준) 버전으로 둔다
• 필요에 따라 현지화 버전(예: AGENTS.<locale>.md)을 추가한다
• clone 이후 각 협업자가 자신의 언어에 맞는 symlink를 로컬에서 만든다:

# 영어 사용자
ln -s AGENTS.en.md AGENTS.md

• symlink 충돌을 피하려면 .gitignore에 AGENTS.md를 추가한다

핵심 인사이트
신뢰할 수 있는 AI 협업의 비밀은 “더 나은 프롬프트”가 아니라, “제약을 저장소의 일부로 만드는 것”입니다. AGENTS.md는 규칙을 재사용 가능하게 만들고, AI Playbook은 문맥을 오래 살립니다.

Step 2: docs/ai-playbook/index.md 만들기 (고신호 진입점)

• 30초 안에 읽히기: “프로젝트 스냅샷 + 링크 인덱스”만
• 원클릭 내비게이션: code-map / flows / collab-rules로 바로 이동

# AI Playbook — Index

## Project Snapshot

- Stack: Next.js / Node / ...
- Red lines: ...

## Document Index

- Code map: docs/ai-playbook/code-map.md
- Key flows: docs/ai-playbook/flows.md
- Collaboration rules: docs/ai-playbook/collab-rules.md

Step 3: code-map.md 만들기 (어디를 고칠지)

• 핵심 디렉터리와 핵심 엔트리 파일만 나열
• 엔트리 파일당 한 문장: 책임(무슨 역할인지)
• 새 요청이 오면: 코드 맵에서 3–8개 후보 파일을 먼저 찍고, 그다음 깊게 읽기

자주 쓰는 요청 라우팅

- 새 페이지 / SEO: frontend/app/\*\*/page.tsx + metadata.ts
- i18n 문구: frontend/constants/messages/\*
- 블로그: frontend/content/blog/\* + frontend/lib/blog.ts

• 초안: AI에게 “디렉터리 + 핵심 엔트리 포인트”를 탐색용으로 정리시키기(완벽함이 아니라 길 찾기가 목적)
• 유지: PR/커밋 단위(파일 리스트 기준)로 조금씩 갱신하기. 한 번에 갈아엎지 않기.

Step 4: flows.md 만들기 (어떻게 동작하는지)

• 시퀀스와 불변식을 써두면, AI가 “감으로 패치”하는 일을 줄일 수 있습니다
• 과거에 밟았던 함정을 디버그 체크리스트로 압축해 재사용할 수 있습니다

1. Key flow / sequence (필요하면 Mermaid)
2. Debug checklist (가장 중요한 로그/상태)
3. Micro-plan template (코딩 전에 plan-first 강제)

• 초안: AI에게 end-to-end 흐름 + 핵심 시퀀스 + 불변식을 먼저 복기시키기 → 사람이(특히 레드라인/불변식) 교정 → 문서화
• 유지: 인터페이스/시퀀스가 바뀔 때마다 인크리멘탈로 갱신하기

Step 5: “plan first”를 강제하기

Title: <short, clear title>

Goals
- <what you want to achieve>

Scope / Files
- <list of files you’ll change/add + why>

Approach
- <implementation plan and key design points>

Risks & Mitigations
- <risk> → <mitigation>

Acceptance Criteria
- <verifiable acceptance items>

Rollback
- <how to revert quickly>

Docs to Update
- docs/ai-playbook/index.md / code-map.md / flows.md / collab-rules.md / others?

Validation
- Build: next build
- Manual: <key cases & regression points>

1. index + code-map + flows를 먼저 읽기(read-only, 코드 수정 금지)
2. 현재 상태와 제약을 “자기 말로” 다시 말하기(사람이 1회 교정)
3. 변경 계획을 작성하기(승인 후에만 구현)

주의사항
계획 단계에서 방향을 바로잡아 “만들고 나서 갈아엎는” 일을 줄이세요. single-scope는 롤백 비용을 낮추고, 머지도 쉽게 만듭니다.

Step 5.1: 문맥 지속력 (checkpoint → 새 대화)

# Handoff

## Problem statement (3–5 sentences)

## Confirmed plan (bullets)

## Done / Not done

## Key files and entry points

## Red lines and invariants

## Acceptance & regression checklist

## Next-step checklist

Step 6: 협업을 닫힌 루프로 만들기 (새 동료를 온보딩하듯 agent 대하기)

1. 요청 → 제약( AGENTS.md 인용)
2. 탐색 → 엔트리 포인트( index + code-map 인용)
3. 정렬 → 시퀀스( flows 인용)
4. 계획 → 미니 설계 문서( collab-rules 템플릿 인용)
5. 구현 → 작고 single-scope(쉽게 롤백)
6. 검증 → next build + 핵심 수동 회귀 포인트
7. 동기화 → playbook 문서 최신화

• 계획 단계에서 방향을 바로잡아, 나중에 버리는 일을 줄인다
• single-scope는 롤백 비용을 낮추고 머지를 쉽게 만든다
• flows는 과거의 함정을 체크리스트로 바꿔 재사용한다

• 이 PR에 변경 계획 링크/요약이 포함되어 있나?
• 엔트리 포인트/플로우/인터페이스가 바뀌었다면 docs/ai-playbook/*를 업데이트했나?

바로 쓸 수 있는 프롬프트 예시

OpenAI 참고

• Role: 품질 기준과 책임 범위를 고정한다
• Task kickoff: playbook을 강제로 읽게 만들어, 추측을 줄인다
• Working style: “plan first”를 워크플로의 일부로 만든다

업계 사례: OpenAI는 Codex로 스프린트를 어떻게 굴리나

• agent를 “새로 온 시니어”로 대하기: 능력은 강하지만, 아키텍처/제약이 명확해야 한다
• 규칙 외부화: 강한 AGENTS.md는 시간이 갈수록 이득이다
• 실질 변경 전에 계획: 계획은 미니 설계 문서 — 코드를 디버그하기 전에 계획을 디버그한다
• 문맥 지속력: 문맥 한계에 닿으면, 계획을 파일로 남겨 다음 세션에서 이어간다
• 멀티 세션 병렬: 단일 도구가 아니라 “팀을 운영”하는 감각에 가깝다

그대로 복사 가능한 최소 디렉터리 구조

AGENTS.en.md             # Canonical rules (English)
AGENTS.<locale>.md       # Optional localized rules
AGENTS.md                # Symlink (created locally after git clone)
docs/
  ai-playbook/
    index.md             # High-signal entry point
    code-map.md
    flows.md
    collab-rules.md

다음 행동

1. 바로 시작: 최소 구조를 저장소에 복사하고, AGENTS.md부터 시작하기
2. 참고 구현: PrivyDrop GitHub에서 전체 AI Playbook 보기
3. 피드백: 도움이 됐거나(혹은 함정에 빠졌다면) GitHub issue를 열거나 댓글로 공유하기
4. Star: 가치가 있다면 PrivyDrop에 star를 🌟

마무리