막연한 아이디어를 작업 명세로 바꾸기

Codex 입문 코스를 마쳤다면 인터넷에 올라간 소개 페이지와 Git 저장소가 하나 있을 거예요. 이번 코스에서는 그 사이트에 오늘 할 일 웹앱을 붙입니다. 할 일을 적고, 끝낸 항목을 체크하고, 새로고침해도 목록이 남는 작은 도구예요.

하지만 오늘은 코드를 한 줄도 만들지 않아요. 먼저 “할 일 앱 하나 만들어 줘”를 Codex가 판단할 수 있는 명세로 바꿉니다. 요리를 시작하기 전에 주문표부터 쓰는 날이에요.

오늘 만들 것

프로젝트 안에 TASK_APP_BRIEF.md가 생겨요. 이 문서에는 네 가지가 들어갑니다.

• 목표 — 누구의 어떤 문제를 해결하는가
• 맥락 — 지금 프로젝트의 파일과 이미 정한 방식은 무엇인가
• 제약 — 이번에는 하지 않을 것과 반드시 지킬 것은 무엇인가
• 완료 조건 — 무엇을 직접 확인해야 끝났다고 부를 수 있는가

이 네 칸은 Codex 공식 모범 사례가 권하는 기본 구조예요. 모든 프롬프트를 장문으로 쓸 필요는 없지만, 여러 파일을 바꾸는 작업에서는 결과의 흔들림을 크게 줄여 줍니다.

준비물

• 입문 코스에서 배포한 first-page 폴더
• VS Code와 Codex
• 약 30분

따라 하기

1. 프로젝트 상태부터 읽게 하기

VS Code에서 first-page 폴더를 열고 Codex 패널에 아래처럼 말하세요.

이 프로젝트를 수정하지 말고 먼저 살펴봐 줘.
현재 파일 구조, 실행 방법, Git 상태, 배포 방식, AGENTS.md의 규칙을
초보자도 이해할 수 있게 다섯 줄 이내로 요약해 줘.
확인하지 못한 것은 추측하지 말고 '확인 못 함'이라고 표시해.

여기서 핵심은 수정하지 말고와 추측하지 말고예요. 에이전트에게 탐색만 맡길 때는 행동의 경계를 먼저 적습니다. 요약에 낯선 말이 나오면 바로 물어보세요. “그중 내가 지금 알아야 하는 말만 비유로 설명해 줘”면 충분해요.

2. 아이디어를 인터뷰로 좁히기

이제 만들고 싶은 것을 말하되, 바로 구현하지 못하게 한 번 더 선을 그어요.

기존 소개 페이지에 '오늘 할 일' 웹앱을 추가하고 싶어.
아직 코드는 쓰지 마. 먼저 범위를 정하기 위해 나에게 질문해 줘.

질문은 한 번에 하나씩, 최대 여섯 개만 해 줘. 아래 결정을 꼭 포함해:
- 누가 어떤 상황에서 쓰는지
- 꼭 필요한 기능 세 가지
- 저장 방식과 개인정보 경계
- 모바일에서 가장 중요한 동작
- 이번 버전에서 하지 않을 것
- 끝났다고 판단할 확인 방법

답에는 정답이 없어요. 다만 첫 버전은 작게 잡으세요. 이 코스의 기본 선택은 다음과 같습니다.

• 한 사람이 자기 브라우저에서 사용
• 할 일 추가, 완료, 삭제, 전체·할 일·완료 필터
• 서버나 회원가입 없이 브라우저 localStorage에만 저장
• 한국어 UI, 휴대폰 한 손 사용, 키보드 사용 가능
• 날짜, 알림, 계정, 다른 기기 동기화는 다음 버전으로 미룸

localStorage는 같은 브라우저 안에만 남아요. 비밀번호나 주민번호 같은 민감한 정보는 적지 않는 도구라고 명세에 써 두세요.

3. 네 칸짜리 명세 만들기

질문에 답한 뒤 아래 주문을 넣으세요.

방금 합의한 내용을 TASK_APP_BRIEF.md로 작성해 줘.

문서는 목표, 사용자, 필수 기능, 제약, 하지 않을 일, 완료 조건 순서로 써.
완료 조건은 모호한 표현 대신 사람이 직접 통과 여부를 확인할 수 있는
체크박스로 만들어 줘. 아직 HTML, CSS, JavaScript는 만들거나 수정하지 마.
작성 후 네가 임의로 결정한 부분이 있다면 따로 알려 줘.

Codex가 만든 문서를 열고 읽으세요. “예쁘게”, “잘 작동한다”처럼 통과 여부가 애매한 말이 있으면 바꿔야 해요. 예를 들면 이렇게요.

나쁜 완료 조건: 모바일에서도 보기 좋다.
좋은 완료 조건: 폭 360px 화면에서 가로 스크롤 없이 추가·완료·삭제할 수 있다.

4. 범위 밖 접시를 치우기

Codex는 친절해서 아이디어를 자꾸 더 얹을 수 있어요. 달력, 우선순위, 로그인, 알림이 등장했다면 지금은 하지 않을 일로 옮기세요.

이 명세를 첫 주말 프로젝트 크기로 다시 검토해 줘.
필수 기능이 아닌 것은 '하지 않을 일'로 옮기고, 왜 미뤘는지 한 줄씩 적어 줘.
파일은 TASK_APP_BRIEF.md만 수정해.

작은 범위는 타협이 아니라 완주의 기술이에요. 이번 코스가 끝나면 미뤄 둔 항목 하나를 다음 프로젝트로 고를 수 있습니다.

막혔을 때

• Codex가 바로 코드를 만들었어요 — Git 변경사항에서 되돌린 뒤 “이번 작업에서는 TASK_APP_BRIEF.md만 바꿔”라고 범위를 다시 지정하세요.
• 질문이 너무 기술적이에요 — “구현 용어 대신 사용자가 보게 될 결과로 질문해 줘”라고 말하세요.
• 완료 조건이 열 개를 넘어요 — 핵심 동작 다섯 개, 접근성 두 개, 저장 한 개 정도만 남기세요.
• 기존 프로젝트가 없어요 — 먼저 입문 5강과 6강을 마치거나 새 Git 폴더를 만든 뒤 진행하세요.

마무리 체크

□ TASK_APP_BRIEF.md가 프로젝트에 있다
□ 목표·맥락·제약·완료 조건이 모두 적혀 있다
□ 서버·회원가입·동기화는 이번 범위에서 빠져 있다
□ 완료 조건을 사람이 직접 PASS/FAIL로 판단할 수 있다
□ 오늘은 앱 코드를 만들지 않았다

좋은 요청은 멋진 단어가 아니라 끝의 모양이 보이는 주문이에요. 다음 강에서는 이 명세를 들고도 바로 코딩하지 않습니다. 먼저 /plan으로 요리 순서를 정해요.