1. 역방향 명세

앞선 책에서 명세서는 만들기 전에 쓰는 문서였습니다. 이 책에서 명세는 만든 뒤에 씁니다. 그것도 여러분이 아니라 Claude가 씁니다. 완성된 결과물을 보고 "이것은 무엇이고, 어떻게 만들어졌고, 어디를 고치면 무엇이 바뀌는가"를 정리하는 문서입니다. 이 책에서는 이것을 역방향 명세라고 부르겠습니다.

왜 굳이 만든 뒤에 명세를 남길까요. 세 가지 이유가 있습니다.

1. 다음 버전을 위해: 한 달 뒤에 기능을 하나 더하려고 폴더를 열면 무엇이 무엇인지 기억나지 않습니다. 명세가 있으면 그것을 읽고 브리프를 씁니다.
2. 다른 사람에게 넘기기 위해: 프로토타입이 잘 되어 개발자와 협업하게 되면, 개발자가 처음 묻는 것이 "이거 어떻게 만들어진 거예요?"입니다. 명세가 그 답입니다.
3. 내가 이해하기 위해: 2장에서 '만들어진 것을 어느 정도는 이해해야 한다'고 했습니다. Claude가 쓴 명세를 읽는 것이 가장 쉬운 이해 방법입니다.

2. 명세 시키기

검토가 끝나고 결과물이 쓸 만해졌을 때, 같은 폴더에서 요청합니다.

이 폴더의 결과물을 보고 `명세.md` 파일을 써줘. 읽는 사람은 개발을 전혀 모르는 나 자신이야. 아래 순서로 써줘.

1. 이 페이지가 무엇을 하는지 세 줄
2. 폴더에 있는 파일마다 무슨 역할인지 한 줄씩
3. 화면 구성을 위에서 아래로, 각 부분이 어느 파일의 어디에 있는지
4. 주문 내용이 어디로 어떻게 저장되는지, 그림으로 (머메이드)
5. 내가 자주 고치게 될 것(가격, 사진, 문구, 연락처)을 어디서 고치면 되는지
6. 이번에 일부러 넣지 않은 것과, 다음에 넣으려면 무엇이 필요한지
7. 이 페이지를 개발자에게 넘길 때 알려줘야 할 것

읽는 사람이 '개발을 모르는 나'라고 분명히 적는 것이 중요합니다. 그러지 않으면 개발자를 위한 문서가 나옵니다. 아래는 이렇게 시켜서 나온 명세의 일부입니다.

# 한라 감귤 농장 주문 페이지 명세

## 1. 이 페이지가 하는 일
지인에게 카카오톡으로 링크를 보내면, 받은 사람이 감귤 종류와 수량, 배송지를 적어 주문을 보낼 수 있습니다. 보낸 주문은 농장주의 구글 시트 '감귤주문'에 한 줄씩 쌓입니다. 회원가입과 결제는 없습니다.

## 2. 파일 역할
- index.html: 화면 전체. 사진, 가격표, 주문 칸이 모두 이 파일에 있습니다.
- style.css: 색, 글자 크기, 폰 화면 배치. 색을 바꾸려면 이 파일 맨 위의 `--main-color`를 고칩니다.
- script.js: 주문하기 버튼을 눌렀을 때 입력 내용을 구글 시트로 보내는 동작.
- photos/: 감귤 사진 3장.
- 명세.md: 이 문서.

## 5. 자주 고칠 것
| 고칠 것 | 파일 | 위치 |
| --- | --- | --- |
| 가격 | index.html | `<!-- 가격표 시작 -->` 아래 |
| 농장 전화번호 | index.html | 맨 아래 `<footer>` 안 |
| 사진 | photos/ | 같은 이름으로 파일만 교체 |
| 주문이 저장되는 시트 | script.js | 맨 위 `SHEET_URL` |

## 6. 이번에 넣지 않은 것
- 주문 확인 문자 발송: 문자 발송 서비스 가입과 비용이 필요합니다.
- 관리자 화면: 주문 현황은 구글 시트에서 직접 봅니다.
- 재고 관리: 품절 표시는 index.html에서 손으로 바꿉니다.

이 문서를 읽으면 여러분이 폴더 안의 파일을 처음으로 '이해'하게 됩니다. 코드를 읽은 것이 아닌데도요.

3. 명세를 브리프로 되돌리기

한 달 뒤, 품절 표시를 자동으로 하고 싶어졌다고 합시다. 폴더를 열고 명세.md를 읽습니다. '이번에 넣지 않은 것'에 재고 관리가 있고, 왜 안 넣었는지도 적혀 있습니다. 이제 브리프를 씁니다.

@명세.md 를 읽어. 이 페이지에 품절 기능을 추가하고 싶어.

- 구글 시트에 '재고' 탭을 만들고 거기 수량이 0이면 페이지에서 그 종류에 '품절'이 표시되고 주문이 안 되게
- 나머지 화면과 동작은 그대로
- 개발을 모르는 내가 유지보수할 수 있는 가장 단순한 방법으로, 만들기 전에 방법을 먼저 알려줘
- 끝나면 명세.md도 같이 고쳐줘

첫 줄에서 명세를 지목했습니다. Claude는 폴더를 처음부터 뒤지지 않고 명세를 읽어 맥락을 잡습니다. 마지막 줄에서 명세도 같이 고치라고 했습니다. 이렇게 하면 명세가 결과물과 함께 자랍니다. 앞선 책에서 '살아있는 문서'라고 불렀던 것이 이것입니다. 다만 그때는 여러분이 손으로 갱신해야 했고, 지금은 Claude가 합니다.

4. 개발자에게 넘길 때

프로토타입이 반응이 좋아 실제 서비스로 키우기로 했다고 합시다. 2장에서 말한 4단계, 백엔드와 데이터베이스가 필요한 단계입니다. 이때 개발자에게 건네는 것은 세 가지입니다.

1. 폴더 전체: 5장에서 GitHub에 올려 두었다면 저장소 주소.
2. 명세.md: 특히 7번 '개발자에게 넘길 때 알려줘야 할 것'.
3. 브리프의 역사: 첫 브리프부터 마지막 브리프까지. 무엇이 바뀌었는지가 곧 여러분이 무엇을 원하는지입니다.

개발자에게 넘기기 전에 Claude에게 한 번 더 시킬 수 있습니다.

이 폴더를 전문 개발자에게 넘겨서 실제 서비스로 키우려고 해. 개발자가 읽을 `핸드오프.md`를 써줘. 지금 구조의 한계, 실제 서비스로 갈 때 바꿔야 할 것, 그대로 가져가도 되는 것을 구분해서. 이번에는 개발 용어를 써도 돼.

이 문서가 앞선 책의 '개발자를 위한 요구사항 템플릿'이 있던 자리를 대신합니다. 여러분이 ERD와 API 명세를 쓰는 것이 아니라, 동작하는 프로토타입과 그것을 설명하는 문서를 건네고, 개발자가 그 위에서 명세를 씁니다. 2장 1절에서 말한 "이렇게 만들어봤는데, 여기서부터 도와주실 수 있나요?"가 바로 이 순간입니다.

5. 남길 것과 버릴 것

프로젝트가 끝났을 때 폴더에 남아 있어야 하는 것을 정리합니다.

브리프와 검토 메모를 파일로 남기는 습관을 권합니다. 폴더 안에 brief.md 하나를 만들고, 브리프를 쓸 때마다 날짜와 함께 아래에 붙여 두면 됩니다. 2장 5절에서 '프롬프트 템플릿을 가져다 쓰는 것보다 자신만의 방식을 찾아야 한다'고 했는데, 그 방식은 이 파일에 쌓입니다. 앞선 책이 '코드가 아니라 프롬프트가 자산'이라고 했던 말은 이 책에서도 유효합니다. 다만 그 자산이 만들기 전의 명세서가 아니라, 만들면서 다듬어진 브리프와 검토 메모, 그리고 만든 뒤의 명세라는 점이 다릅니다.