03 · AI 협업
이번 강의에서 배울 것
- AI가 저장소에서 아는 것과 이번 작업에서 모르는 것을 구분한다.
- 목표·위치·재료·경계·확인을 짧은 프롬프트로 적는다.
- 계획→구현→확인→설명→AI 리뷰 순서로 Issue 하나를 진행한다.
- AI에 넣으면 안 되는 비밀 값과 개인정보를 가짜 데이터로 바꾼다.
1. 이 강의를 읽으면
다 읽고 나면 긴 기획서를 매번 붙여 넣지 않고도 AI가 필요한 정보를 골라 줄 수 있습니다. AI가 범위를 벗어나거나 없는 파일을 지어냈을 때도 결과를 그대로 믿지 않고 바로잡을 수 있습니다.
Codex·Claude의 화면과 기능은 버전에 따라 달라질 수 있습니다. 이 강의의 프로젝트 파일과 작업 규칙은 2026년 10월 29일 학생회 플랫폼 저장소를 기준으로 합니다.
2. 개념 설명
2-1. AI는 저장소를 읽지만 목표를 마음대로 정할 수 없다
코딩 AI는 저장소의 파일을 검색하고 코드를 읽을 수 있습니다. 실행 명령을 돌리고 오류를 확인하며, 허용된 범위에서 파일을 수정할 수도 있습니다.
하지만 AI는 이번 주 회의에서 정한 목표, Issue에만 적힌 완료 기준, 아직 코드에 반영되지 않은 결정을 저절로 알 수 없습니다.
AI가 코드를 잘 읽는 것과 우리가 원하는 결과를 아는 것은 다른 일입니다. 사람이 목표와 경계를 주지 않으면 AI는 그럴듯하지만 다른 기능을 만들 수 있습니다.
2-2. AI가 이미 아는 것
우리 저장소에는 AI가 작업 전에 읽는 규칙 파일이 있습니다.
| AI 도구 | 먼저 읽는 규칙 |
|---|---|
| Codex | AGENTS.md |
| Claude Code | CLAUDE.md, 그리고 그 파일이 안내하는 AGENTS.md |
이 파일에는 다음과 같은 프로젝트 공통 규칙이 들어 있습니다.
- 기술 스택과 Node.js 버전
- Issue 하나 = 브랜치 하나 = PR 하나
- 팀원이 수정할 수 없는 공용 파일
- DB·RLS·서버 함수는 리드의 기반 작업이라는 경계
- 로딩·빈 목록·오류·권한 없음 화면 확인
- lint·typecheck·test·build 검사 명령
- RLS 우회, 테스트 삭제, 실제 개인정보 사용 금지
- 커밋·PR 제목과 주간 일정
공통 규칙을 매 프롬프트에 다시 복사하면 중요한 작업 정보가 묻힙니다. AI가 이미 읽는 내용은 반복하지 않습니다.
2-3. AI가 모르는 것
AI에게 알려 줄 것은 이번 작업에서만 정해지는 정보입니다.
| 항목 | 사람이 답할 질문 | 예시 |
|---|---|---|
| 목표 | 무엇이 되면 끝인가? | 국원이 자기 업무를 마감일 순으로 본다 |
| 위치 | 어느 파일에서 작업하나? | src/app/tasks/page.tsx |
| 재료 | 이미 준비된 무엇을 쓰나? | tasks 조회 함수, EmptyState |
| 경계 | 이번에 하지 않을 것은 무엇인가? | 필터 기능은 다음 Issue |
| 확인 | 어떻게 성공을 판단하나? | 빈 목록과 오류를 Preview에서 확인 |
다섯 칸을 항상 새로 쓸 필요는 없습니다. 대부분은 Issue의 목표·수정 가능한 파일·이미 준비된 것·완료 기준·이번에 하지 않는 것에 들어 있습니다.
AI가 GitHub Issue를 직접 읽을 수 없는 상황이라면 Issue 본문을 붙여 넣습니다. 제목이나 Issue 번호만 주고 내용을 알고 있을 것이라고 가정하지 않습니다.
2-4. 전공자처럼 쓰는 것은 정확한 단어를 쓰는 것
좋은 프롬프트는 길고 어려운 문장이 아닙니다. 작업 위치와 실행 방식이 달라지는 지점에서 정확한 단어를 쓰는 문장입니다.
목록 화면 만들어 줘.위 문장만으로는 AI가 어느 파일을 고칠지, 서버와 브라우저 중 어디에서 조회할지, 빈 목록을 어떻게 보여 줄지 알 수 없습니다.
src/app/tasks/page.tsx를 Server Component로 만들고, 준비된 tasks 조회 함수를 호출해 목록을 보여 줘.
조회 부분은 Suspense로 감싸고, 빈 결과는 EmptyState로 보여 줘.두 번째 문장은 길지 않지만 파일 경로, Server Component, 조회 함수, Suspense, EmptyState가 들어 있어 선택이 분명합니다.
앞으로 필요한 단어는 나머지 강의에서 배웁니다.
| 영역 | 프롬프트에 쓰는 단어 예시 |
|---|---|
| GitHub | 브랜치, 커밋, PR, 충돌, CI |
| Next.js | 경로, Server Component, Client Component, Suspense, Server Action |
| React UI | 컴포넌트, props, state, 폼, label, focus |
| Supabase | 테이블, select, insert, update, RPC, 타입 |
| 권한 | 로그인, Role, Position, RLS, 허용·거부 |
| 디버깅 | 콘솔, Network, 오류 메시지, typecheck, 테스트 |
2-5. 계획 → 구현 → 확인 → 설명 → AI 리뷰
AI 작업은 한 번의 긴 프롬프트로 끝내지 않습니다. 한 단계의 결과를 확인한 뒤 다음 단계로 넘어갑니다.
| 순서 | 사람이 할 일 | AI에 요청할 것 |
|---|---|---|
| 1. 계획 | 범위와 준비물을 확인 | 바꿀 파일과 방법만 먼저 제안 |
| 2. 구현 | 계획이 Issue와 맞는지 승인 | 승인한 계획대로 코드 수정 |
| 3. 확인 | 화면과 검사 결과를 직접 봄 | 검사 실행, 오류 원인 설명 |
| 4. 설명 | 변경 이유를 자기 말로 정리 | 초보자에게 코드 흐름 설명 |
| 5. AI 리뷰 | PR 전 누락과 위험을 찾음 | Issue 기준으로 현재 diff 리뷰 |
계획 단계에서 공용 파일이나 supabase/**를 바꾸겠다고 하면 코드가 생기기 전에 멈출 수 있습니다.
확인 단계는 AI가 "완료했습니다"라고 말하는 것을 읽는 단계가 아닙니다. 명령 출력과 Preview 화면을 사람이 직접 보는 단계입니다.
설명 단계에서 왜 바꿨는지 답하지 못하면 리뷰에서 Merge할 준비가 되지 않은 것입니다.
AI 리뷰는 사람 리뷰를 대신하지 않습니다. 작성자가 놓친 부분을 한 번 더 찾는 0단계 리뷰입니다.
2-6. AI에 넣으면 안 되는 정보
다음 정보는 Codex·Claude·Issue·PR·채팅에 넣지 않습니다.
.env.local의 내용- API Secret key, service role key, DB 비밀번호
- OAuth Client Secret과 GitHub·Vercel 토큰
- 실제 학생 이름·이메일·학번
- 실제 건의 원문과 회의록의 민감한 내용
- 비밀 값이나 개인정보가 보이는 화면 캡처
오류가 비밀 값과 함께 보이면 값만 ***로 가리고 오류 문구와 환경변수 이름을 전달합니다.
실제 데이터가 필요한 것처럼 보여도 같은 모양의 가짜 데이터를 만듭니다.
이메일: test.member@example.com
학번: 2026000000
이름: 테스트사용자가짜 값은 실제 사람과 우연히 겹치지 않게 명확한 테스트 값으로 씁니다.
3. 우리 저장소에서 보기
3-1. AGENTS.md
저장소 루트의 AGENTS.md는 Codex가 따라야 할 실행 규칙입니다.
다음 부분을 찾아보면 AI가 무엇을 이미 알고 있는지 확인할 수 있습니다.
AGENTS.md
├─ 기술 스택과 Node.js 버전
├─ Issue·브랜치·PR 규칙
├─ 공용 파일 목록
├─ DB·RLS 작업 경계
├─ 화면 확인 항목
├─ 검사 명령
├─ 보안 금지 사항
└─ 주간 리듬프롬프트에 "Next.js 16이고 Tailwind를 쓰고…"를 매번 적지 않는 이유입니다.
3-2. CLAUDE.md
CLAUDE.md는 Claude Code가 먼저 읽는 짧은 작업 규칙입니다. 상세 규칙은 AGENTS.md와 TF 작업 가이드를 따르도록 연결되어 있습니다.
두 파일의 역할이 겹치더라도 서로 다른 규칙을 새로 만들지 않습니다. 프로젝트의 기준 문서는 하나로 맞춰야 AI마다 다른 결과가 나오지 않습니다.
3-3. Issue 템플릿
.github/ISSUE_TEMPLATE/task.md는 AI가 모르는 다섯 항목을 거의 그대로 담고 있습니다.
| Issue 템플릿 | AI 프롬프트의 역할 |
|---|---|
| 목표 | 목표 |
| 수정 가능한 파일 | 위치와 경계 |
| 이미 준비된 것 | 재료 |
| 완료 기준 | 확인 |
| 이번에 하지 않는 것 | 경계 |
그래서 새 설명을 길게 쓰기보다 Issue 본문을 주고 "계획부터 보여 줘"라고 덧붙이는 방식이 효율적입니다.
3-4. PR 템플릿
.github/pull_request_template.md에는 AI를 어떻게 썼는지와 사람이 직접 확인한 결과를 적는 칸이 있습니다.
AI 사용에는 도구 이름과 핵심 요청 한 줄을 적습니다. 전체 대화를 복사할 필요는 없습니다.
직접 확인한 것에는 검사 명령, Preview, 권한 없는 계정 결과를 적습니다. AI가 실행했다고 주장한 내용이 아니라 작성자가 확인한 사실을 적습니다.
잘 모르는 부분에는 리뷰어가 자세히 봐야 할 부분을 솔직하게 씁니다.
3-5. 실제 코드와 Issue의 재료 비교
예를 들어 src/app/me/page.tsx에는 실제로 Suspense, profiles, memberships 조회가 있습니다.
AI에게 이 파일을 수정시키기 전에 파일을 검색해 해당 재료가 정말 있는지 확인합니다. Issue에 EmptyState를 쓰라고 적혀 있는데 검색 결과가 없다면, 이름을 비슷하게 지어내지 말고 리드에게 준비 여부를 확인합니다.
4. 프롬프트에 쓰는 법
4-1. Issue를 시작할 때
나쁜 예
학생회 업무 기능을 전부 만들어 줘.좋은 예
Issue #12를 구현해 줘. 아래 Issue 본문을 기준으로 바꿀 파일과 방법만 먼저 계획해 줘.
내가 승인하기 전에는 코드를 수정하지 마.한 번에 Issue 하나만 요청합니다. 여러 기능을 함께 주면 범위와 확인 기준이 섞입니다.
4-2. 짧은 화면 수정을 요청할 때
나쁜 예
빈 화면 예쁘게 해 줘.좋은 예
src/app/tasks/page.tsx에서 조회 결과가 비었을 때 기존 EmptyState를 보여 줘.
문구는 "아직 배정된 업무가 없습니다"로 해 줘.위치, 빈 결과라는 상태, 사용할 재료, 원하는 문구가 들어 있습니다.
4-3. 오류를 고칠 때
나쁜 예
안 돼요. 빨리 고쳐 줘.좋은 예
npm run typecheck에서 아래 오류가 발생해.
오류가 뜻하는 것과 원인을 먼저 설명하고, 관련 파일만 고쳐 줘. (오류 메시지 붙여 넣기)오류 메시지는 요약하거나 바꾸지 말고 그대로 줍니다. 다만 키·개인정보는 가립니다.
4-4. 코드를 이해할 때
나쁜 예
이 코드 설명해 줘.좋은 예
src/app/me/page.tsx에서 Suspense를 쓴 이유와 AccountDetails가 실행되는 순서를 웹 개발 초보자에게 설명해 줘.
브라우저·서버·DB 중 어디서 실행되는지도 구분해 줘.설명받을 파일과 이해하고 싶은 부분을 지정합니다.
4-5. 결과를 확인할 때
나쁜 예
다 잘됐는지 확인해 줘.좋은 예
Issue #12의 완료 기준과 현재 변경을 비교해 확인해 줘.
실행한 검사와 실행하지 못한 검사를 나누고, Preview에서 사람이 직접 확인할 항목을 적어 줘.AI가 검사를 실행할 수 있어도 화면의 문구와 사용 흐름은 사람이 직접 봐야 합니다.
4-6. AI 리뷰를 요청할 때
나쁜 예
코드 괜찮지?좋은 예
Issue #12와 현재 diff를 비교해 리뷰해 줘.
범위 밖 파일, 화면 상태 4가지, 권한 없는 직접 접근, 테스트 누락을 우선 찾아 줘.리뷰 기준을 주면 단순한 요약보다 누락과 위험을 찾기 쉽습니다.
4-7. 비밀이 포함된 오류를 물어볼 때
나쁜 예
.env.local 전체와 오류 화면을 붙여 넣을게. 왜 안 되는지 봐 줘.좋은 예
NEXT_PUBLIC_SUPABASE_URL을 읽지 못한다는 오류가 발생해.
값은 공유하지 않을게. 환경변수 이름과 로딩 위치를 기준으로 원인을 설명해 줘. (비밀 값을 가린 오류 메시지)AI가 문제를 풀기 위해 실제 비밀 값이 필요한 경우는 거의 없습니다.
5. AI 결과 확인하기
5-1. AI가 자주 틀리는 것
| 실수 | 사람이 확인할 것 |
|---|---|
| Issue보다 큰 기능을 한 번에 만듦 | 목표와 변경 파일이 Issue 하나 범위인지 |
| 존재하지 않는 함수·테이블·컴포넌트를 지어냄 | 저장소 검색과 "이미 준비된 것"이 일치하는지 |
| 공용 파일·DB·패키지까지 수정함 | 허용된 파일 밖의 diff가 있는지 |
| 버튼을 숨기고 권한 구현이 끝났다고 함 | 권한 없는 직접 요청을 RLS가 거부하는지 |
| 오류를 없애려고 테스트를 삭제함 | 테스트 수와 변경된 테스트 의도가 맞는지 |
| 성공 화면만 만들고 상태를 빠뜨림 | 로딩·빈 목록·오류·권한 없음이 있는지 |
| 명령을 실행하지 않고 "통과"라고 씀 | 실제 명령 출력과 종료 코드가 있는지 |
| 오래된 문서나 계획 코드를 실제 코드로 착각함 | 현재 파일 경로와 구현 여부를 확인했는지 |
| 설명은 하지만 작성자가 이해하지 못함 | 코드를 보지 않고 변경 이유를 말할 수 있는지 |
5-2. 한 단계가 끝날 때 확인할 것
계획 뒤에는 바꿀 파일이 Issue의 허용 범위 안인지 봅니다.
구현 뒤에는 git diff로 AI가 실제로 무엇을 바꿨는지 봅니다.
검사 뒤에는 성공·실패·실행하지 못한 명령을 나누어 기록합니다. 화면은 Preview에서 직접 누릅니다.
설명 뒤에는 "왜 이 파일인가", "왜 Server Component인가", "권한은 어디서 막나" 같은 질문에 자기 말로 답합니다.
AI 리뷰 뒤에는 지적을 무조건 적용하지 않습니다. Issue와 현재 코드에 맞는지 판단한 뒤 반영합니다.
5-3. PR을 올리기 전 마지막 질문
아래 질문에 모두 답할 수 있어야 합니다.
- 사용자는 무엇을 할 수 있게 되었나?
- 어떤 파일을 왜 바꿨나?
- 준비된 함수·타입·컴포넌트 중 무엇을 사용했나?
- 이번에 하지 않은 것은 무엇인가?
- 정상·빈 목록·오류·권한 없음은 어떻게 확인했나?
- 권한 없는 계정의 직접 접근은 어디서 막히나?
- 실행한 검사와 실행하지 못한 검사는 무엇인가?
답을 모르겠다면 PR을 서두르지 말고 AI에게 해당 부분을 다시 설명해 달라고 요청합니다.
6. 확인 질문
AGENTS.md에 기술 스택과 검사 명령이 이미 있습니다. 새 Issue를 시작할 때 사람이 AI에게 추가로 알려 줘야 할 정보는 무엇인가요?
정답 확인
이번 Issue의 목표, 수정할 위치, 이미 준비된 재료, 이번에 하지 않을 경계, 완료를 확인할 방법입니다. 대부분 Issue 본문에 있으므로 프로젝트 공통 규칙을 다시 복사하기보다 Issue와 필요한 한두 문장을 줍니다.
AI가 "구현을 완료했고 테스트도 통과했다"고 말했습니다. 바로 PR을 올리면 안 되는 이유와 사람이 할 일을 말해 보세요.
정답 확인
AI의 완료 문장은 증거가 아닙니다. 사람이 변경 파일을 Issue 범위와 비교하고, 실제 검사 출력과 종료 코드를 확인하며, Preview에서 화면 상태와 권한 없는 직접 접근을 확인해야 합니다. 그 뒤 변경 이유를 자기 말로 설명하고 AI 리뷰를 한 번 더 받습니다.
오류 화면에 실제 학생 이메일과 API 키가 함께 보입니다. AI에게 어떻게 질문해야 하나요?
정답 확인
학생 이메일은 명확한 가짜 값으로 바꾸고 API 키는 ***로 가립니다. 환경변수 이름, 오류 메시지, 기대 결과만 전달합니다. 비밀 값이 보이는 원본 화면이나 .env.local 전체는 보내지 않습니다.
내용을 이해했다면 학습 완료를 체크해 주세요.