AI가 이해하는 스펙 작성법
개발자를 위한 실전 가이드
"AI한테 명세를 어떻게 써줘야 제대로 코드가 나올까요?"
최근 가장 많이 받는 질문입니다. ChatGPT, Claude, Copilot... 다들 쓰고는 있는데, 원하는 결과가 안 나온다는 거죠.
비밀을 알려드릴게요: AI는 컴파일러처럼 생각하세요.
컴파일러에게 문법 틀린 코드를 주면? 에러가 나죠. AI도 마찬가지입니다. 명세가 모호하면 결과도 모호합니다.
사람을 위한 명세 vs AI를 위한 명세
10년 전과 지금의 차이를 보겠습니다.
10년 전에는 사람이 읽는 명세를 썼습니다. "로그인 기능, 이메일과 비밀번호로 로그인, 성공시 대시보드로 이동, 실패시 에러 표시" 이런 식으로요. 개발자가 알아서 나머지를 채워넣을 거라 기대했죠.
지금은 AI가 읽는 명세를 씁니다. Function 이름, Method 경로, Input의 타입과 형식, Output의 구조, Business Logic의 단계별 절차, Error Cases의 모든 예외 상황까지 명시합니다. AI는 암묵적 지식이 없습니다. 모든 걸 명시해야 합니다.
차이가 보이시나요? AI는 사람과 다릅니다. 사람은 "로그인 기능"이라고만 해도 세션 관리, 보안, 로깅, 에러 처리까지 떠올리지만, AI는 그런 암묵적 지식을 갖고 있지 않습니다.
AI 친화적 명세의 5가지 원칙
첫 번째는 구조화입니다. AI는 구조를 좋아합니다. 자유 형식보다는 정형화된 포맷을 사용하세요. "사용자가 로그인하면 토큰을 주고 대시보드로 보내고 실패하면 에러 메시지를 보여주는데 5번 틀리면 잠그고..." 같은 나열식보다는, Steps로 1. 입력 검증, 2. DB 조회, 3. 비밀번호 확인, 4. 토큰 생성, 5. 응답 반환으로 구조화하고, Error Handling도 Case별로 명확히 나누는 것이 좋습니다.
두 번째는 구체화입니다. "적절히", "필요시", "일반적으로" 같은 모호한 표현은 금물입니다. "적절한 검증 수행" 대신 "이메일: RFC 5322 형식 검증", "캐싱: Redis, TTL 3600초", "에러: 400(검증), 401(인증), 500(서버)"처럼 구체적으로 명시하세요.
세 번째는 예시 포함입니다. AI는 예시를 통해 패턴을 학습합니다. Valid Input과 Expected Output, Invalid Input과 Expected Error를 구체적인 값으로 보여주면 AI가 더 정확한 코드를 생성합니다.
네 번째는 제약사항 명시입니다. 기술적 제약(Node.js 18+, Express 4.x, PostgreSQL 14+, JWT 사용), 비즈니스적 제약(비밀번호 최소 8자, 토큰 유효기간 1시간, 동시 로그인 3개까지, GDPR 준수), 성능 제약(응답시간 < 200ms, 동시 요청 1000/s)을 명확히 하세요.
다섯 번째는 테스트 케이스입니다. 테스트 케이스를 명세에 포함하면 AI가 더 정확한 코드를 생성합니다. 정상 로그인, 잘못된 이메일, 계정 잠금 등 각 시나리오의 input과 expected output을 명시하세요.
실전: 결제 시스템 명세 작성
실제 프로젝트에서 사용한 명세입니다. System 이름, Purpose, Version을 명시하고, Architecture를 다이어그램으로 보여주고, API Endpoints를 하나씩 상세히 정의합니다. Create Subscription의 경우, Request의 headers와 body 구조, Response의 200 OK와 400 Bad Request, 402 Payment Required 케이스를 모두 명시하고, Business Rules를 1부터 4까지 번호를 매겨 나열합니다. Implementation Details도 Stripe Customer 생성/조회, Payment Method 첨부, Subscription 생성, DB 저장, 이메일 알림 발송까지 단계별로 명시합니다.
Database Schema는 CREATE TABLE과 CREATE INDEX까지 포함하고, Error Handling은 PaymentError 클래스의 구조와 사용 예시를 보여줍니다. Testing은 Unit Tests와 Integration Tests를 구분하고, Monitoring은 Metrics와 Alerts를 명시합니다.
이런 명세를 AI에게 주면, 프로덕션 레벨의 코드가 나옵니다.
AI별 명세 작성 팁
ChatGPT는 대화형으로 점진적 개선이 가능하고, "이전 코드를 기반으로..."를 활용하며, 컨텍스트 유지가 중요합니다. Claude는 한 번에 전체 명세를 제공하고, 긴 문서도 잘 처리하며, 구조화된 출력을 요청하세요. GitHub Copilot은 주석으로 명세를 작성하고, 함수 시그니처를 먼저 작성하며, 테스트를 먼저 작성하면 더 정확합니다.
명세 템플릿 모음
제가 실제 사용하는 템플릿들입니다. API 엔드포인트는 Endpoint, Purpose, Authentication, Request, Response, Errors, Business Logic을 포함합니다. 데이터 모델은 Model 이름, Table 이름, Fields, Relations, Indexes, Validations를 명시합니다. 비즈니스 로직은 Function 이름, Input, Output, Preconditions, Postconditions, Steps, Edge Cases를 포함합니다.
마무리: 명세는 투자다
"명세 쓸 시간에 코딩하는 게 빠르지 않나요?"
예전엔 그랬을지도 모릅니다. 하지만 AI 시대에는 다릅니다.
명세 작성 30분 = AI 코드 생성 3분 = 수동 코딩 3시간
명세를 잘 쓰면 AI가 정확한 코드를 생성하고, 팀원과 명확히 소통하며, 문서화가 자동 완성되고, 테스트 케이스가 명확해집니다.
명세는 비용이 아니라 투자입니다.
특히 WBS와 결합하면 더 강력합니다. WBS의 각 태스크마다 명확한 명세를 작성하면, AI가 전체 프로젝트를 거의 자동으로 구현할 수 있습니다.
다음에 AI를 쓸 때는 "대충" 요청하지 마시고, 제대로 된 명세를 작성해보세요.
놀라운 결과를 보게 될 겁니다.
AI 시대의 프로젝트 관리와 명세 작성이 필요하신가요? Plexo를 확인해보세요.