YKSS
AI 에이전트를 위한 좋은 스펙 작성법
Addy Osmani 의 5원칙: 고수준 비전 → AI 가 세부를 초안 / PRD 6 영역 / 모듈형 프롬프트 / 3단계 경계(Always/Ask/Never) / 반복 테스트. 요약: 스펙을 '덜 쓰는' 게 아니라 '다르게 쓴다'.
핵심 요약
Addy Osmani 의 가이드를 5원칙으로 압축. (1) 고수준 비전은 사람이, 세부는 AI 가 초안 — 사람이 모든 칸을 채우지 않는다. (2) PRD/SRS 6영역 구조 — Commands / Testing / Project Structure / Code Style / Git Workflow / Boundaries. (3) 모놀리식 프롬프트 대신 모듈형 — 영역별 파일로 나눠 재사용. (4) 3단 경계 — Always do / Ask first / Never do 로 AI 의 자유도 범위를 그림으로 고정. (5) 반복 테스트 + tooling — 스펙이 한 번에 완성되지 않으며, AI 답변을 보고 빈칸을 메우는 피드백 루프. 면접에서 AI 협업 경험을 말할 때 이 5원칙을 프레임으로 쓰면 구체적 설계 감각이 드러난다.
AI 시대 스펙 작성을 '사람에게 지시하는 문서' → 'AI 가 자율 결정할 경계를 긋는 문서' 로 본다. 모든 세부를 쓰는 게 아니라, (a) 절대 규칙, (b) 물어봐야 할 영역, (c) AI 가 알아서 할 영역 을 구분해 표시한다.
AI 도입 팀에서 가장 흔한 실패는 '시킨 대로 잘 하는데 엉뚱한 게 나옴' 이다. 원인은 스펙이 사람용 문법 이라는 점. PRD 에 '좋은 UX' 같은 추상 표현이 있으면 AI 는 임의 해석을 한다. 해결은 경계가 명시된 구조 로 스펙을 재설계하는 것.
학습 포인트
면접 답변으로 연결할 학습 포인트입니다.
3단 경계 — 자유도를 그림으로
AI 에게 맡길 범위를 세 층으로 명시한다.
| 단계 | 예시 | 의미 |
|---|---|---|
| Always do | 새 훅 이름은 use 로 시작 | 매번 자동 적용 |
| Ask first | 새 라이브러리 추가 | 실행 전에 확인 질문 |
| Never do | lodash 추가, 전역 eslint-disable | 해당 시도 시 중단 |
이 분류 없이 '알아서 잘 해줘' 는 무한 해석 공간. 반대로 '모든 걸 시킨 대로만' 은 AI 의 가치가 사라진다. 경계가 자유도의 품질을 결정한다.
Always 와 Never 만 두고 Ask 를 빼는 것 — 실제 애매한 영역(신규 의존성, 스키마 변경)에서 AI 가 추측하게 된다.
모듈형 프롬프트 — 하나의 큰 파일 금물
모놀리식 프롬프트는 세 가지 문제를 낳는다. (1) 컨텍스트 오염 — 관련 없는 규칙이 답변에 섞임, (2) 유지보수 난이도 — 한 줄 수정이 전체 영향 평가 필요, (3) 재사용 불가.
prompts/
├── base.md # 항상 포함
├── testing-rules.md # PR 생성 시에만
├── style-rules.md # UI 작업에만
└── db-rules.md # 스키마 변경에만
도구(Claude Code, Cursor) 가 맥락에 맞게 자동 로드 하도록 태깅.
모든 규칙을 CLAUDE.md 한 파일에 몰아넣는 것. 100줄 넘으면 분리 신호.
반복 테스트 — 스펙은 초안일 뿐
좋은 스펙은 처음부터 완성되지 않는다. 절차:
- 초안 작성 (주요 영역만)
- AI 로 1주 사용
- 'AI 가 엉뚱하게 한 순간' 3개 기록
- 해당 항목을 스펙에 추가/수정
- 다시 1주
이 사이클이 3~4회 돌면 스펙이 팀의 실제 의사결정 이력 을 반영하게 된다. '완벽 스펙' 을 처음부터 쓰려는 시도는 과학 아닌 소설.
문서 한 번 쓰고 스프린트 진행. 실제로는 일주일 단위 미니 회고 로 갱신해야 품질 유지.
읽는 순서
- 1이론
Addy Osmani 원문 +
CLAUDE.md/AGENTS.md표준 3개를 읽고 공통 영역 6개(Commands/Testing/Project/Style/Git/Boundaries) 로 매핑. - 2구현
본인 프로젝트에 Always/Ask/Never 를 각 5항목씩 넣은
BOUNDARIES.md를 별도 파일로 작성하고CLAUDE.md에서 참조. - 3실무
1주일 AI 사용 후 '엉뚱한 순간' 3개를 로그로 기록하고, 각각이 Always/Ask/Never 중 어느 쪽에 빈칸이었는지 분류.
- 4설명
팀에 'AI 스펙 5원칙 체크리스트' 를 한 장 배포하고, 다음 PR 템플릿에 '경계 업데이트' 항목 추가.
면접 연결 질문
[좋은 답변] (1) Always do 에 폴더 구조 예시 를 박음, (2) Ask first 에 '새 폴더 생성 전 확인', (3) 기존 파일 3개를 예시로 보여 규칙을 추론 가능 하게. 규칙 나열이 아니라 예시 + 경계.
[좋은 답변] (1) AI 가 무한 질문 루프 — 매 액션마다 승인 요청, (2) 사람이 병목, (3) 결국 AI 도입 ROI 가 -. 자유도 축소는 속도 축소 와 등가.
[좋은 답변] (1) PR 리뷰 대상에 CLAUDE.md 포함, (2) 월간 회고에 'AI 규칙 충돌 사례' 섹션, (3) 팀 투표 아닌 합의된 기록 — 결정 배경을 주석으로 남김.
자기 점검
Always 에 '원칙' 만 추상적으로 적는 것 — 구체적 패턴 이어야 함.
'모델이 멍청해서' 로 끝내는 것 — 대부분은 스펙 빈칸.