가이드개발·연동

SPECS.md로 AI 코딩 요구사항을 정리하는 법

AI 코딩 작업의 요구사항을 SPECS.md에 고정하고, 명세·계획·작업·구현을 분리해 변경 사항과 검토 기준을 잃지 않는 워크플로우입니다.

1
성공 조건을 문서로 적습니다
사용자 흐름, 제약, 완료 기준, 검증 방법을 구현 요청보다 먼저 SPECS.md에 기록합니다.
2
명세를 구현 계획으로 나눕니다
변경할 파일과 데이터, 위험 요소, 테스트 방법을 별도 계획으로 정리해 에이전트가 추측할 범위를 줄입니다.
3
작업을 검증 단위로 쪼갭니다
작업 목록을 작은 완료 조건으로 분리하고, 각 작업에 필요한 테스트를 연결합니다.
4
변경은 대화가 아니라 명세에도 반영합니다
요구사항이 바뀌면 SPECS.md와 계획을 먼저 갱신하고, 구현과 문서가 어긋나지 않는지 다시 확인합니다.

대화 대신 기준 문서를 남깁니다

AI 코딩에서는 대화가 길어질수록 무엇이 확정됐는지 흐려지기 쉽습니다. SPECS.md는 제품 요구와 완료 기준을 한곳에 두어, 새 세션이나 다른 에이전트도 같은 기준으로 작업하게 합니다.

명세와 구현을 한 번에 섞지 않습니다

GitHub Spec Kit의 기본 흐름은 Spec, Plan, Tasks, Implement를 구분합니다. 각 산출물이 다음 단계의 입력이 되므로, 구현을 시작하기 전에 빠진 제약과 테스트를 발견하기 쉽습니다.

문서도 변경 대상입니다

요구가 바뀌었는데 코드만 바꾸면 다음 작업에서 이전 가정이 되살아납니다. 변경의 이유와 영향 범위를 명세·계획·작업 목록에 함께 반영하고, 실제 구현과 대조합니다.

공식 자료: GitHub Spec Kit