코덱스를 한 달쯤 써 보면 패턴이 보입니다. 잘 되는 날과 잘 안 되는 날의 차이는 코덱스의 컨디션이 아니라, 내가 일을 얼마나 잘 정의했는지에 달려 있다는 것을요. 이번 레슨에서는 실전에서 효과가 입증된 원칙들을 정리합니다.
원칙 1: 작게 쪼개서 시키기
"인증 시스템 전체를 새로 만들어줘"와 "로그인 폼에서 이메일 유효성 검사 로직만 추가해줘"는 같은 AI에 맡기는 완전히 다른 작업입니다. 작업이 클수록 코덱스가 중간에 판단을 내려야 할 지점이 많아지고, 그 판단이 여러분의 의도와 어긋날 가능성도 높아집니다. 하나의 작업은 하나의 완료 조건으로 정의하세요.
원칙 2: 명세를 정확히 (Specification)
코덱스는 추측을 잘하지만, 추측이 필요 없게 명세를 쓰는 것이 더 낫습니다. 좋은 명세는 무엇을(What), 어디를 건드려도 되는지(Scope), 어떻게 확인하는지(Verification) 세 가지를 담습니다.
명세 작성 나쁜 예 vs 좋은 예
--- 나쁜 예 (추측 의존) ---
검색 기능 성능 개선해줘.
--- 좋은 예 (명세 완비) ---
목표: 상품 검색 API 응답 시간을 현재 평균 800ms에서 200ms 이하로 줄여줘.
범위: src/api/products/search.ts 만 수정할 것. DB 스키마는 건드리지 마.
제약: 기존 응답 JSON 구조는 바꾸지 않는다.
완료 조건: GET /api/products/search?q=test 를 10번 호출해서
평균 응답 시간이 200ms 이하인 것을 확인해줘.원칙 3: 결과 검토 체크리스트
- diff 읽기: git diff로 바뀐 파일과 줄 수를 직접 확인합니다. 생각보다 많이 바뀌었다면 범위를 초과한 것입니다.
- 의도치 않은 파일 변경: 범위로 지정하지 않은 파일이 바뀌지 않았는지 확인합니다.
- 테스트 통과: npm test가 실패 없이 통과하는지 봅니다.
- 새 의존성 추가 여부: package.json이 바뀌었다면 어떤 패키지가 추가됐는지 검토합니다.
- 하드코딩 시크릿: API 키, 패스워드, 토큰이 코드에 직접 박혀 있지 않은지 확인합니다.
- 커밋 메시지: 변경 내용을 정확히 설명하는지 봅니다.
흔한 실수와 해결법
| 흔한 실수 | 왜 일어나나요? | 해결법 |
|---|---|---|
| 작업 범위가 예상보다 크게 바뀜 | 명세에 Scope를 명시하지 않아서 | "src/auth/ 폴더 안만 수정"처럼 폴더를 명확히 지정 |
| 테스트 통과해도 기능이 이상함 | 테스트가 실제 요구사항을 반영 못 했거나 부족해서 | 완료 조건에 직접 실행해 볼 수 있는 확인 방법 추가 |
| 같은 실수를 반복함 | 실수를 AGENTS.md에 기록하지 않아서 | 실수가 생길 때마다 AGENTS.md에 금지 규칙으로 추가 |
| 코덱스가 도중에 헤맴 | 작업이 너무 크거나 완료 조건이 애매해서 | 작업을 더 작은 단계로 나누고 단계마다 확인 포인트 추가 |
| 의존성이 무단으로 추가됨 | AGENTS.md에 의존성 추가 금지 규칙이 없어서 | AGENTS.md에 "패키지 추가 전 먼저 제안" 규칙 추가 |
병렬 작업 분배 전략
클라우드에서 작업을 병렬로 돌릴 때는 파일이 겹치지 않도록 분배하는 것이 핵심입니다. 같은 파일을 두 작업이 동시에 수정하면 나중에 머지할 때 충돌이 생깁니다.
병렬 작업 분배 예시 (파일 겹침 없음)
작업 A: src/components/UserCard.tsx 유닛 테스트 추가
작업 B: src/api/analytics.ts 에러 핸들링 보강
작업 C: src/utils/dateFormatter.ts 한국어 날짜 포맷 추가
# 세 작업이 서로 다른 파일을 건드리므로 충돌 없이 병렬 실행 가능합니다.
# 완료 후: 각 PR을 개별 리뷰하고 순서대로 머지합니다.하루를 시작할 때 포스트잇처럼 작고 명확한 작업 카드를 미리 만들어 보세요. 각 카드에 범위와 완료 조건을 한 줄씩 적으면, 그것이 곧 코덱스에게 줄 프롬프트의 초안이 됩니다.
베스트 프랙티스는 처음부터 완벽하게 지키려 하면 오히려 속도가 느려집니다. 오늘 당장 하나만 골라 시작하세요. "작업 범위를 폴더 하나로 제한하기"만 지켜도 코덱스 경험이 확연히 달라집니다.