“알림 설정 하나 추가해 줘.” AI 코딩 에이전트는 곧바로 토글과 저장 버튼을 만들었다. 화면도 멀쩡했고 저장도 됐다. 그런데 일반 사용자에게는 보이면 안 되는 관리자 기능이었고, 저장 실패 때 값이 원래대로 돌아오지 않았으며, 모바일에서는 오류 문구가 버튼을 밀어냈다.
에이전트가 코드를 못 만든 것은 아니었다. 누가 쓰는지, 어디까지 만들지, 무엇을 확인해야 끝나는지가 코딩 전에 정해지지 않았던 게 문제였다. 프롬프트를 더 길게 쓰기보다 세 가지 결정을 짧은 문서로 나누자 재작업의 이유가 보이기 시작했다.
잘못된 코드는 대부분 코드 밖에서 시작됐다
사람끼리는 “우리 서비스답게”라는 말만 들어도 기존 화면과 지난 회의를 떠올린다. 저장소를 처음 읽는 에이전트에게 그런 기억은 없다. 대상 사용자와 범위가 비어 있으면 현재 코드에서 눈에 띄는 패턴이나 흔한 화면을 골라 빈칸을 채운다.
알림 설정 기능에서도 질문은 네 개면 충분했다. 관리자만 쓰는가, 이메일만 다루는가, 저장 실패를 어떻게 보여 줄 것인가, 기존 설정 화면의 모바일 규칙을 따르는가. 이 답이 없으면 첫 결과는 빨라도 두 번째 수정에서 API와 화면을 함께 다시 만들게 된다.
그래서 AI 코딩의 첫 단계는 더 좋은 명령문을 꾸미는 일이 아니다. 아직 사람이 결정하지 않은 부분을 구현 전에 발견하는 일에 가깝다.
코딩 전에는 세 문서만 짧게 남겼다
SPEC.md는 문제와 경계를 맡았다. “관리자가 장애 알림 이메일을 켜고 끈다”를 이번 범위로 두고, 앱 푸시와 발송 이력은 다음 작업으로 뺐다. 완료 조건에는 관리자 권한, 저장 실패 복구, 모바일 화면을 적었다.
PLAN.md는 파일 목록보다 확인 순서를 담았다. 기존 권한 검사를 먼저 찾고, API 계약을 고정한 뒤, 화면을 붙이고, 마지막에 권한·저장 실패·모바일 회귀를 검사하도록 했다. 중간에 기존 저장 방식이 예상과 다르면 코드를 밀어붙이지 않고 계획부터 고친다.
DESIGN.md는 화면의 기억을 남겼다. 본문 폭과 모바일 여백, 주 행동 색상, 오류 상태, 쓰지 않을 장식만 적었다. 색상값만 주는 대신 “주 행동에만 사용하고 위험 행동에는 쓰지 않는다”처럼 사용 조건을 함께 붙였다.
알림 설정 기능에 실제로 남긴 최소 문장
SPEC — 관리자만 사용, 이메일 알림만 이번 범위, 실패 시 이전 값 복원.
PLAN — 권한 확인 → API 계약 → 화면 상태 → 실패·모바일 테스트.
DESIGN — 모바일 여백 19px, 저장 중 중복 클릭 금지, 오류는 색상과 문구로 표시.
문서가 길어질 필요는 없다. 서로 다른 파일에 같은 말을 반복하지 않고, 구현 중 새 사실을 발견했을 때 담당 문서 한 곳만 고치면 된다. 중요한 것은 형식이 아니라 다음 작업에서도 판단 근거가 남는가다.
도구 여섯 개는 세 갈래로 보면 쉬워진다
세 문서는 손으로 만들어도 충분하다. 같은 질문과 검증을 자꾸 반복하게 될 때 도구를 붙이면 된다. 유명한 도구를 모두 설치하기보다 지금 막힌 지점에 맞는 흐름 하나를 고르는 편이 결과도 단순하다.
아이디어가 흐리다면 Superpowers가 먼저 질문하고 계획과 테스트로 넘어가는 습관을 잡아 준다. 새 프로젝트에서 팀이 같은 순서를 따라야 한다면 GitHub Spec Kit의 Spec → Plan → Tasks → Implement 흐름이 더 명확하다.
이미 운영 중인 코드라면 OpenSpec이 가볍다. 기존 코드를 살피고 작은 변경 제안을 만드는 데 초점을 두기 때문이다. 반대로 PM·설계·개발·QA처럼 역할과 검토 단계가 실제로 많은 프로젝트라면 BMAD를 검토할 만하다. 개인의 작은 기능에는 문서 검토 비용이 더 클 수 있다.
선택은 결국 간단하다. 질문이 부족하면 Superpowers, 새 팀의 절차가 필요하면 Spec Kit, 기존 코드의 작은 변경이면 OpenSpec, 역할이 많은 큰 작업이면 BMAD다. 한 프로젝트에 네 가지를 모두 붙일 이유는 없다.
화면이 자꾸 흔들릴 때는 도구 하나로 해결되지 않는다. DESIGN.md는 색·간격·금지 패턴과 그 이유를 보존한다. shadcn/ui MCP는 에이전트가 레지스트리에서 버튼·폼·대화상자 같은 부품을 찾고 추가하도록 돕는다.
하나는 규칙이고 다른 하나는 부품이다. 규칙 없이 부품만 가져오면 다른 서비스와 비슷한 화면이 나오기 쉽고, 부품 없이 규칙만 있으면 같은 구현을 반복하게 된다.
내 프로젝트에는 무엇부터 붙이면 될까
혼자 만드는 작은 기능 — 세 문서를 각각 세 줄로 직접 쓴다. 반복 수정이 생긴 부분만 OpenSpec이나 Superpowers로 보강한다.
새로 시작하는 팀 프로젝트 — Spec Kit로 공통 흐름을 맞추고, 화면 작업이 많을 때 DESIGN.md를 추가한다.
역할과 승인 단계가 많은 프로젝트 — BMAD를 작은 기능 하나에 시험해 문서량과 검토 비용부터 확인한다.
도입 테스트도 작게 한다. 새 브랜치에서 로그인 오류 문구처럼 경계가 분명한 기능 하나를 고르고, 도구 없이 만든 결과와 도구를 거친 결과를 비교한다. 질문 횟수, 사람이 다시 고친 문장, 실행된 테스트, 최종 변경 파일이 줄었는지 보면 된다.
어떤 방식을 골라도 에이전트의 “완료했습니다”라는 문장은 검증 결과가 아니다. 실행한 테스트와 확인한 화면, 아직 남은 제한이 함께 나와야 사람이 다음 판단을 이어 갈 수 있다.
좋은 도구라면 기능이 끝난 뒤에도 왜 이 범위를 골랐고 무엇으로 확인했는지가 남는다. 코드보다 중간 문서가 많고 같은 설명이 반복된다면 절차를 줄일 신호다. 도구를 제거해도 SPEC과 테스트, 결정 근거가 읽혀야 다음 에이전트와 다음 프로젝트에서도 다시 쓸 수 있다.
AI 코딩의 품질은 첫 코드가 나오는 속도보다, 틀린 가정을 얼마나 일찍 발견하는가에서 갈린다. 코딩 버튼을 누르기 전 세 문장을 남기는 일이 오히려 가장 빠른 시작일 수 있다.
참고한 공식 자료
- GitHub Spec Kit 공식 문서
- Superpowers 공식 저장소
- OpenSpec 공식 저장소
- BMAD Method 공식 저장소
- Google Labs DESIGN.md 공식 저장소
- shadcn/ui MCP 공식 문서
- 요즘IT: AI 에이전트와 함께 쓰는 기획·디자인 도구 소개
확인 기준일: 2026년 8월 7일. 설치 명령과 지원 환경은 바뀔 수 있으므로 사용 전 공식 문서를 다시 확인한다.
'실전 개발 노트 > 개발 가이드' 카테고리의 다른 글
| PostgreSQL EXPLAIN ANALYZE로 느린 쿼리 해결하기: 인덱스와 통계 읽는 법 (0) | 2026.08.05 |
|---|---|
| PyTorch U-Net 이미지 세그멘테이션: 구조·Dice Loss·반려동물 실습 (0) | 2026.08.01 |
| 딥러닝 학습 원리: 순전파·역전파·옵티마이저·L1/L2 규제 (0) | 2026.07.31 |
| VAE·GAN·Diffusion 차이: 이미지 생성 원리와 선택 기준 (0) | 2026.07.31 |
| TypeScript 7 마이그레이션 가이드: Go 네이티브 컴파일러 전환 전 확인할 것 (0) | 2026.07.31 |
