헌법(Constitution)을 정했다면, 다음은 명세서입니다. /speckit.specify

이 명령어는 '무엇을 만들고 싶은지'를 AI에게 전달하면, 대화 과정을 통해 요구사항을 정리하고 spec.md 파일을 생성 및 업데이트해 주는 커맨드입니다.

여기서 가장 중요한 포인트는 구현의 세부 사항이 아니라 '어떤 사용자 경험을 제공하고 싶은지', '어떤 비즈니스 규칙이 있는지'를 작성하는 것입니다. '명세서'라고 들으면 구체적인 클래스 이름이나 라이브러리 이름을 쓰고 싶게 되지만, 이 단계에서는 그렇지 않고, 사용자 관점에서 어떤 서비스로 만들고 싶은지를 작성합니다. 기술 선정은 더 후반 과정(계획)에서 진행합니다.

이 시리즈에서는 지금까지 'Spec Kit의 구조', 'Constitution 설정'을 다루었습니다. 함께 읽으면 도입부터 실전까지 한 번에 이해할 수 있습니다.

/speckit.specify가 어떤 커맨드인지 알게 됩니다 – 명세서에 '작성해야 할 것'과 '작성하지 말아야 할 것'의 경계가 파악됩니다.

• 생성되는 specs/001-.../spec.md의 구성(사용자 스토리, 엣지 케이스, 성공 기준 등)을 읽을 수 있습니다 – 동시에 생성되는 checklists가 무엇을 위한 것인지 알게 됩니다 – 헌법의 지시가 제대로 작동하지 않을 때(영어로 반환되는 경우 등) 수정하는 방법을 알게 됩니다.

명세서 작성은 헌법 다음, 계획(plan) 앞에 위치하는 공정입니다.

이 단계에서 작성하는 것은 'What(무엇을)'과 'Why(왜)'입니다. 'How(어떻게 구현할지)'는 작성하지 않습니다. 이 둘을 혼동하면 아직 결정되지 않은 기술적인 이야기가 명세서에 섞여 들어가 후반 공정이 흐트러집니다.

그림의 왼쪽(사용자 관점)에 집중하는 것이 좋은 명세서의 첫걸음입니다.

에디터로 돌아가 Copilot 채팅 에이전트 선택에서 speckit.specify를 선택합니다. 이번에는 인사 관리 시스템의 첫 기능으로 직원 목록 화면을 만들 것입니다.

단순히 '직원 목록 화면을 만들고 싶다'만 해도 작동하지만, 그 화면의 목적이나 역할을 간단하게 덧붙여주면 AI가 의도를 파악하기 쉽습니다. 예를 들어 다음과 같은 형태입니다.

직원 목록 화면을 만들고 싶습니다.
이 화면을 보면 어떤 직원이 있는지, 각각의 역할・직책・나이・근속 연수 등,
많은 정보가 알 수 있도록 해주세요.
...

이 프롬프트를 입력하고 실행합니다.

생성이 완료되면 specs라는 디렉토리가 생기고, 그 안에 번호가 매겨진 폴더가 만들어집니다. 이번에는 001-employee-list라는 이름이 되었습니다. 명세서를 늘려갈수록 다음은 002-...와 같이 번호가 증가합니다(이 번호는 Git 브랜치에도 대응합니다).

파일 구성은 대략 다음과 같습니다.

인사 관리 시스템/
└── specs/
└── 001-employee-list/
...

spec.md에는 브랜치명・날짜・상태 같은 메타 정보에 이어, 다음과 같은 요소들이 작성됩니다.

사용자 스토리 / 사용자 시나리오: 기술적인 이야기가 아니라, '시스템에 로그인하면 탑 화면에서 직원 목록이 보인다'와 같이 어떻게 사용될지에 대한 개요 -
엣지 케이스: 자주 일어나지는 않지만 발생할 수 있는 경우. 예를 들어 직원 수가 1000명을 초과했을 때의 성능, 동명이인 처리, 퇴직자 처리 등 -
비기능 요구사항: 스마트폰 대응 등 기능 자체 외의 요구사항 -
성공 기준(success criteria): 결과적으로 어떤 동작을 해야 '잘 구현되었다'고 말할 수 있는지

사용자 스토리는 독립적으로 테스트 가능한 가치 단위로 우선순위(P1・P2 등)와 함께 정리되기도 합니다. 대략 읽어보고 이상한 점이 없으면 다음으로 넘어가도 괜찮습니다.

spec.md와 함께 checklists 폴더에 품질 검사용 파일도 만들어집니다. 이것은 명세서의 질(완전성・명확성)을 평가하는 체크리스트입니다. 처음에 정한 프로젝트의 검증 조건을 충족하고 있는지 확인해 나가는 위치지이며, 검증이 끝나면 완료로 기록됩니다.

이 체크리스트는 일종의 '영어로 된 (자연어) 단위 테스트'입니다. 구현 후 QA 테스트가 아니라, 구현을 시작하기 전에 '요구사항이 제대로 작성되었는지'를 검증하는 용도라고 이해하면 헷갈리지 않습니다. 파일명이나 항목은 버전에 따라 달라질 수 있습니다.

생성되는 요소들을 정리하면 다음과 같습니다.

/speckit.specify

는 「무엇을 만들 것인가」를 전달하여 spec.md를 만드는 커맨드라고 이해했습니다.

• 구현 상세(클래스 이름 등)가 아니라, 사용자 경험(UX)·비즈니스 규칙(What / Why)을 작성했습니다.
• 화면의 목적이나 역할을 가볍게 덧붙여, AI가 의도를 파악할 수 있도록 했습니다.
• 생성물이 specs/001-<기능명>/spec.md로 번호가 매겨져 생성되는 것을 확인했습니다.
• spec.md의 유저 스토리(User Story), 엣지 케이스(Edge Case), 성공 기준(Success Criteria)을 훑어보았습니다.
• checklists는 요구사항의 품질 체크(QA가 아님)라고 이해했습니다.
• 헌법(Constitution)의 지시가 제대로 작동하지 않는다고 느껴지면, 다시 헌법으로 돌아가 지시를 강화하는 흐름을 알고 있습니다.

명세서가 완성되었으니, 드디어 「무엇을 만들 것인가」에서 「어떻게 만들 것인가」로 넘어갑니다. 다음 회차에서는 이 명세서를 바탕으로 계획(plan)을 수립하는 공정을 진행하겠습니다.