저는 평소에 AI한테 코드 시킬 때 나름의 규칙이 있었어요.
막연하게 “뭐 만들어줘” 하면 안 되고, 명확하게 지시해야 한다는 건 이미 알고 있었거든요.
그래서 Addy Osmani의 “How to write a good spec for AI agents” 글을 봤을 때, 처음엔 “뭐, 다 아는 내용이겠지” 싶었어요.
근데 읽어보니까…
“어, 이건 나랑 비슷하네” 하는 부분도 있고,
“오, 이건 내가 안 하던 건데?” 하는 부분도 있더라고요.
그래서 다른 부분을 몇 개 적용해봤어요.
결과? 진짜 좋아졌어요.
오늘은 그 이야기를 해볼게요.
내 방식과 비슷했던 부분
1. “막연한 지시는 실패한다”
Addy Osmani 글에서 이런 문장이 있었어요.
“Most agent files fail because they’re too vague.” (AI 에이전트가 실패하는 이유는 대부분 프롬프트가 너무 막연해서다.)
이건 저도 이미 알고 있었어요.
저도 처음엔 “로그인 만들어줘” 이렇게 시켰다가 엉뚱한 코드 받고 학습했거든요.
그래서 지금은 이렇게 시켜요:
"POST /api/auth/login 엔드포인트 만들어줘.
입력: { email: string, password: string }
출력: { token: string, user: { id, name, email } }
JWT 사용, httpOnly 쿠키로 저장"
비슷하네. Addy가 말하는 “명확한 스펙”이랑 제 방식이 거의 같았어요.
2. “작업을 쪼개라”
Addy가 강조한 게 이거였어요.
“Avoid asking the AI for large, monolithic outputs. Instead, break the project into iterative steps.” (한 번에 큰 걸 시키지 말고, 작은 단계로 쪼개라.)
이것도 저랑 비슷했어요.
저도 “인증 시스템 전체 만들어줘” 이렇게 안 시켜요.
1단계: JWT 유틸 함수 2단계: 로그인 API 3단계: 인증 미들웨어 4단계: 테스트 코드
이렇게 쪼개서 시키거든요.
읽으면서 “오, 나도 이렇게 하고 있었네” 하는 안도감이 들었어요.
내가 완전 틀린 방향으로 가고 있던 건 아니구나.
3. “테스트가 있으면 AI가 정확해진다”
Simon Willison이라는 개발자 말을 인용하더라고요.
“Having a robust test suite is like giving the agents superpowers.” (탄탄한 테스트 코드가 있으면 AI가 슈퍼파워를 얻은 것 같다.)
이것도 공감했어요.
저도 테스트 코드 있을 때랑 없을 때 AI 정확도가 확 다르다는 걸 느꼈거든요.
테스트 없이 “버그 고쳐줘” → AI가 엉뚱한 곳 수정 테스트 있고 “이 테스트 통과하게 고쳐줘” → AI가 정확히 수정
이건 제가 이미 경험으로 알고 있던 거라 “맞아맞아” 하면서 읽었어요.
내가 안 하고 있던 부분 (이게 핵심!)
근데 읽다 보니까 “어, 이건 내가 안 하던 건데?” 하는 부분이 몇 개 있었어요.
1. SPEC.md 파일로 문서화
저는 AI한테 지시할 때 매번 프롬프트에 스펙을 적었어요.
"Next.js 14 App Router 사용하고, TypeScript strict mode이고, 함수명은 camelCase이고, 에러 처리는 try-catch로 하고..."
매번 이걸 반복해서 썼어요.
근데 Addy는 이걸 파일로 만들어두라고 하더라고요.
프로젝트 루트/ ├── SPEC.md ← 이걸 만들어두고 ├── src/ └── ...
AI한테 “SPEC.md 읽고 코드 짜줘” 하면 끝이래요.
“아, 이거 왜 진작 안 했지?”
매번 같은 내용 반복해서 쓰느라 시간 낭비하고 있었던 거예요.
2. AI한테 자기 검증 시키기
이게 진짜 신박했어요.
코드 만들고 나서 AI한테 이렇게 물으래요:
"스펙이랑 비교해서 빠진 거 없는지 체크해줘. 빠진 항목은 리스트로 뽑아줘."
저는 이거 안 하고 있었거든요.
AI가 코드 만들면 제가 직접 스펙이랑 비교하면서 확인했어요.
근데 Addy 말대로 AI한테 시켜봤더니:
✅ 인증 로직 구현 완료 ✅ JWT 발급 완료 ❌ 에러 처리: custom error class 사용 안 함 ❌ 테스트: 작성 안 됨
이렇게 AI가 스스로 체크리스트를 돌려주더라고요.
“야, 두 개 빠졌잖아” 하니까 바로 고쳐줬어요.
제가 직접 확인하는 시간이 확 줄었어요.
3. “AI는 인턴이다”라는 마인드셋
Addy가 이런 말을 했어요.
“AI를 시니어 개발자처럼 대하지 마라. 인턴처럼 대하라.”
저는 은연중에 AI를 **”똑똑한 동료”**처럼 생각하고 있었어요.
“이 정도는 알아서 해주겠지” 하는 기대가 있었던 거죠.
근데 인턴 마인드로 바꾸니까 접근이 달라지더라고요.
인턴한테는 이렇게 시키잖아요:
- 뭘 만들지 (What)
- 왜 만드는지 (Why)
- 제약 조건이 뭔지 (Constraints)
- 어떤 스타일로 해야 하는지 (Style)
- 끝나면 뭘 확인해야 하는지 (Verification)
이걸 다 알려줘야 해요.
AI한테도 똑같이 하니까 결과물 퀄리티가 확 올라갔어요.
적용해봤더니 달라진 점
Before: 매번 같은 스펙 반복 작성
예전에는 AI한테 시킬 때마다 이런 걸 매번 썼어요:
"Next.js 14 App Router 사용, TypeScript strict mode, 함수명 camelCase, 컴포넌트명 PascalCase, 에러 처리 try-catch..."
시간 낭비 + 가끔 빠뜨림 + 일관성 없음
After: SPEC.md 만들어두고 참조
이제는 SPEC.md에 다 적어두고:
"SPEC.md 읽고 로그인 API 만들어줘"
이 한 줄로 끝나요.
AI가 알아서 스펙 기준으로 일관된 코드를 만들어줘요.
체감 효율: 2배 이상
Before: 내가 직접 결과물 검증
코드 받으면 제가 하나하나 확인했어요.
“JWT 제대로 발급했나?” “에러 처리 패턴 맞나?” “컨벤션 지켰나?”
시간 많이 걸림 + 놓치는 것도 있음
After: AI한테 자기 검증 시키기
이제는 코드 받고 바로 이렇게 물어요:
"SPEC.md랑 비교해서 빠진 거 체크해줘"
AI가 알아서 체크리스트 돌려주고, 빠진 거 있으면 바로 고쳐줘요.
제가 직접 확인하는 시간 50% 이상 감소
Before: “똑똑한 동료”에게 기대
은연중에 “이 정도는 알아서 해주겠지” 기대하다가 실망하는 경우가 있었어요.
After: “인턴”에게 명확하게 지시
이제는 모든 걸 명시해요. 알아서 해주길 기대 안 해요.
기대가 낮으니까 실망도 없고, 명확하게 시키니까 결과물도 좋아요.
내가 정리한 AI 스펙 작성 체크리스트
Addy 글 읽고 제 방식이랑 합쳐서 체크리스트를 만들었어요.
이제 AI한테 코드 시킬 때마다 이거 확인해요:
[ ] 목적 (Purpose)이 명확한가? [ ] 입력/출력 (I/O)이 정의되어 있는가? [ ] 기술 스택이 명시되어 있는가? [ ] 코딩 컨벤션이 정해져 있는가? [ ] 제약 사항이 있으면 적었는가? [ ] 작업이 충분히 작게 쪼개졌는가? [ ] AI한테 자기 검증 시킬 건가?
이 체크리스트 쓰기 시작하고 나서 AI랑 협업 속도가 체감 3배는 빨라진 것 같아요.
솔직한 마음
Addy Osmani 글 읽으면서 두 가지 감정이 들었어요.
첫 번째는 안도감.
“내가 완전 틀린 방향으로 가고 있던 건 아니었구나.”
막연한 지시 피하기, 작업 쪼개기, 테스트 활용하기… 이런 건 이미 하고 있었거든요.
두 번째는 아쉬움.
“SPEC.md랑 자기 검증은 왜 진작 안 했지?”
특히 매번 같은 스펙 반복해서 쓰느라 낭비한 시간이 아깝더라고요.
진작 파일로 만들어뒀으면 훨씬 편했을 텐데.
앞으로 내가 할 것들
이 글 읽고 바로 실천하기로 한 것들이에요.
1. 모든 프로젝트에 SPEC.md 만들기
새 프로젝트 시작하면 코드보다 스펙부터 쓸 거예요.
기존 프로젝트도 SPEC.md 추가해서 AI한테 컨텍스트 주기 편하게 만들 거예요.
2. AI한테 항상 자기 검증 시키기
코드 받으면 무조건 “스펙이랑 비교해서 체크해줘” 물을 거예요.
제가 직접 확인하는 시간 줄이고, 놓치는 것도 방지할 수 있어요.
3. “인턴 마인드” 유지하기
AI한테 “알아서 해주겠지” 기대 안 할 거예요.
모든 걸 명시하고, 검증까지 시키는 습관 유지할 거예요.
결론: 비슷하지만 다른 부분이 핵심이었다
Addy Osmani 글 읽으면서 느낀 건 이거예요.
“큰 틀은 비슷하지만, 디테일에서 차이가 났다.”
- 명확하게 지시하기 → 이미 하고 있었음 ✅
- 작업 쪼개기 → 이미 하고 있었음 ✅
- 테스트 활용하기 → 이미 하고 있었음 ✅
- SPEC.md로 문서화 → 안 하고 있었음 ❌ → 적용 후 효율 2배
- AI한테 자기 검증 시키기 → 안 하고 있었음 ❌ → 적용 후 검증 시간 50% 감소
- 인턴 마인드셋 → 은연중에 안 지키고 있었음 ❌ → 적용 후 기대치 관리 개선
결국 다른 부분을 적용했더니 확 좋아진 거예요.
여러분도 이미 AI 잘 쓰고 계실 수 있어요.
근데 혹시 “SPEC.md 파일로 관리”나 “AI 자기 검증” 안 하고 계시다면…
한번 해보세요. 진짜 달라져요.
FAQ
Q1. SPEC.md 너무 길어지면 AI가 다 읽나요?
A: Claude는 200K 컨텍스트라서 긴 스펙도 읽어요. 다만 너무 길면 중요한 거 놓칠 수 있어서, 핵심만 담는 게 좋아요. 상세한 건 별도 문서로 분리하고 SPEC.md에는 “이 프로젝트 이해하는 데 필수적인 것”만 넣으세요.
Q2. 기존 프로젝트에도 SPEC.md 추가해야 하나요?
A: 추천해요. AI한테 “이 프로젝트 분석해서 SPEC.md 초안 만들어줘” 시키면 80% 정도 뽑아줘요. 나머지 20%만 수정하면 돼요. 특히 레거시 프로젝트는 스펙 없으면 AI가 코드 스타일 제멋대로 만들어서 더 지저분해져요.
Q3. 자기 검증 시키면 토큰 더 쓰는 거 아닌가요?
A: 맞아요, 토큰 좀 더 써요. 근데 제가 직접 검증하다가 놓치고 나중에 버그 잡는 것보다 훨씬 효율적이에요. “검증 토큰 조금 더 쓰기 vs 디버깅 시간 한 시간” 비교하면 검증이 이득이에요.
Q4. Cursor나 Windsurf에서도 SPEC.md 쓸 수 있나요?
A: 네! 프로젝트 루트에 SPEC.md 두면 자동으로 컨텍스트에 포함돼요. .cursorrules 파일로도 쓸 수 있어요. 코딩 컨벤션 넣어두면 AI가 일관된 스타일로 코드 짜줘요.