1장 만들기 전에 성공을 정의한다

“AI로 의뢰 관리 서비스를 만들어 줘”는 시작 문장이지 작업 명세가 아니다. AI는 빈칸을 자연스럽게 채우므로, 빈칸이 많을수록 결과는 빨리 나오지만 틀릴 가능성도 커진다. 첫 작업은 기술 선택이 아니라 사용자의 한 문장을 관찰 가능한 행동으로 바꾸는 일이다.

BriefFlow의 핵심 사용자는 소규모 에이전시 운영자다. 고객은 긴 설명을 제출하고, 운영자는 원문과 구조화 결과를 비교하며, 승인된 내용만 후속 작업으로 넘긴다. 성공 기준은 다음과 같이 쓴다.

• 유효한 의뢰를 제출하면 브리프 ID와 성공 결과가 생긴다.
• 동의가 없거나 요구가 너무 짧으면 원인을 알려 주고 브리프 목록에 저장하지 않는다. 현재 예제 서버는 요청 본문을 로그로 남기지 않지만 운영 로그 정책은 별도로 검증한다.
• 견적은 AI의 자유 문장이 아니라 코드의 계산 규칙으로 만든다.
• 외부 행동은 승인자, 만료 시각, 산출물 해시가 있는 영수증을 요구한다.
• 기본 실습은 네트워크와 API 키 없이 반복 가능하다.

좋은 완료 조건은 “깔끔하다”가 아니라 npm run qa가 성공하고, 신규 독자가 README 없이도 본문의 명령으로 화면을 열 수 있다는 식으로 확인 가능하다. AI에게 요청할 때도 목표, 현재 맥락, 제약, 완료 조건을 함께 준다.

목표: 고객 의뢰를 구조화하는 POST /api/briefs를 추가한다.
맥락: Node 표준 라이브러리만 쓰며 domain.mjs에 순수 함수가 있다.
제약: 동의 없는 입력을 저장하지 말고 실제 메일은 보내지 않는다.
완료: 정상·동의 없음·짧은 요구 테스트가 모두 통과한다.

실습: 모호한 문장을 검증 문장으로 바꾸기

“알아서 좋은 견적을 만든다”를 “채널 수와 위험 수로 계산하고 고객 예산을 넘지 않는다”로 바꿔 보자. 전자는 취향을 요구하지만 후자는 테스트할 수 있다. 프로젝트의 test/domain.test.mjs에서 이 규칙이 실제로 고정되어 있다.