티스토리 뷰
AI 코딩 에이전트(Cursor, Windsurf 등)를 사용하다 보면, 방대한 요구사항을 한꺼번에 던졌을 때 갈팡질팡하거나 엉뚱한 코드를 짜는 경험을 하게 됩니다. 핵심은 단순히 요구사항을 나열하는 것이 아니라, AI가 이해하기 쉬운 **'스마트 스펙'**을 설계하는 데 있습니다.
Addy Osmani가 제안하는 효과적인 스펙 작성 및 워크플로우를 정리했습니다.
1. 한 번에 다 주지 마세요: '스마트 스펙'의 흐름
AI에게 처음부터 모든 세부 사항을 주입하는 대신, 점진적인 확장 방식을 선택해야 합니다.
• 비전 제시 (Vision First): 먼저 고수준의 비전과 목표를 제시합니다.
• AI의 확장 (AI Expansion): AI가 그 비전을 바탕으로 세부 계획을 스스로 확장하게 합니다.
• 플랜 모드 (Plan Mode): 바로 코드를 짜게 하지 말고, '읽기 전용' 모드에서 AI가 세운 계획을 먼저 검토합니다.
• 코드 작성 (Act): 계획이 확정된 후에야 실제 구현 단계로 전환합니다.
2. 고수들이 사용하는 스펙의 6가지 필수 요소
GitHub의 2,500개가 넘는 에이전트 설정 파일을 분석한 결과, 가장 효과적인 스펙은 다음 6가지 영역을 명확히 정의하고 있습니다.
1. Commands (명령어): 실행, 빌드, 배포에 필요한 명확한 커맨드.
2. Testing (테스트): 무엇을 어떻게 테스트해야 하는지에 대한 기준.
3. Project Structure (프로젝트 구조): 파일 레이아웃과 모듈 간의 관계.
4. Code Style (코드 스타일): 선호하는 코딩 컨벤션과 문법 규격.
5. Git Workflow (워크플로우): 커밋 메시지 규칙 및 브랜치 전략.
6. Boundaries (경계): AI가 해도 되는 일과 해서는 안 되는 일의 명확한 구분.
3. '경계 설정'의 3단계 법칙
AI가 제멋대로 코드를 수정하지 않도록 3단계 경계를 설정하는 것이 중요합니다.
• Always (항상 수행): 별도의 확인 없이 자동 적용할 표준 절차.
• Ask First (먼저 확인): 파괴적인 변경이나 주요 아키텍처 수정 시 반드시 사용자에게 질문.
• Never (절대 금지): 특정 라이브러리 사용 금지나 보안상 건드리지 말아야 할 영역.
4. 모듈화와 컨텍스트 최적화
거대한 프롬프트 하나는 AI를 혼란에 빠뜨립니다. 대규모 작업은 다음과 같이 관리하세요.
• 태스크 분할: 작업을 작고 독립적인 모듈 단위로 나눕니다.
• 최소 컨텍스트: 해당 태스크를 수행하는 데 꼭 필요한 정보만 제공하여 품질 저하를 방지합니다. 불필요한 정보는 오히려 노이즈가 됩니다.
5. 지속 가능한 스펙 워크플로우
스펙은 한 번 쓰고 버리는 것이 아닙니다. **'테스트 - 반복 - 진화'**의 과정을 거쳐야 합니다. 스펙 내부에 자가 검증(Self-verification) 로직과 적합성 테스트를 내장하여, AI가 결과물을 내놓기 전에 스스로 한 번 더 점검하게 만드세요.
💡 요약하자면
AI 에이전트는 당신의 실력을 복제하는 도구입니다. 좋은 스펙은 AI가 더 똑똑하게 생각하게 만들고, 결과적으로 개발자의 검토 시간을 획기적으로 줄여줍니다. 지금 바로 여러분의 프로젝트 스펙에 **'6가지 핵심 영역'**과 **'3단계 경계'**를 도입해 보세요!
#AI에이전트 #AI코딩 #스마트스펙 #개발생산성 #프롬프트엔지니어링 #AddyOsmani #코딩팁 #소프트웨어공학 #AI개발 #효율성최적화
출처 : https://addyosmani.com/blog/good-spec/