지난 시간의 합의를, 다음 대화가 읽게 만들기

시작 전

오늘 만들 것은 파일 두 개입니다

첫 번째는 에이전트가 매번 먼저 읽는 작업 안내문이고, 두 번째는 무엇을 만들지 정리한 명세입니다. 둘을 한 문서에 섞지 않습니다.

• CLAUDE.md 또는 AGENTS.md: 이 프로젝트에서 일하는 방법을 알려주는 안내문
• Spec(명세): 해결하려는 문제와 이번에 만들 범위를 합의한 문서
• Ticket(작업 카드): Spec을 실제 작업 순서로 나눈 문서. W3에서 다룹니다.

01 · 규칙 파일

CLAUDE.md와 AGENTS.md를 쉽게 이해하기

둘 다 “AI가 이 프로젝트에서 일할 때 먼저 확인하는 안내문”입니다. 이름을 둘 다 만들어야 하는 것은 아니며, 사용하는 도구의 규칙에 맞춰 하나를 고르면 됩니다.

1. 01

   프로젝트를 한 문장으로 소개하기

   왜 하나요? AI가 지금 어느 프로젝트에 들어와 있는지 알게 합니다.

   할 일 누가, 무엇을 위해, 어떤 결과를 만드는 프로젝트인지 한 문장으로 씁니다.

   복사해서 써도 되는 요청

   이 프로젝트의 목적을 비개발자도 이해할 수 있는 한 문장으로 정리해줘. 문서에 없는 내용은 추측하지 마.

   정상이라면 예: “인사 담당자가 교육생 피드백을 빠르게 정리해 공유하는 도구다.”

2. 02

   항상 지킬 규칙을 세 문장만 고르기

   왜 하나요? 매 작업에 반복해서 필요한 판단 기준만 남깁니다.

   할 일 AI가 틀리면 곤란한 판단을 세 가지 고릅니다. “열심히 하자”처럼 확인할 수 없는 말은 뺍니다.

   복사해서 써도 되는 요청

   현재 프로젝트 파일을 먼저 살펴보고, 작업할 때 반복해서 지켜야 하는 규칙 후보를 5개 제안해줘. 각 후보가 없으면 어떤 판단을 틀리는지도 함께 써줘. 파일은 아직 수정하지 마.

   정상이라면 후보 목록을 받은 뒤 사람이 3개 이하를 선택합니다.

   TIP · AI에게 곧바로 파일을 쓰게 하지 말고, 조사 → 제안 → 승인 순서로 진행합니다.

3. 03

   상세 내용은 위치만 알려주기

   왜 하나요? 규칙 파일이 길어져 중요한 문장이 묻히는 것을 막습니다.

   할 일 자세한 절차·예시·배경은 별도 문서에 두고, 규칙 파일에는 어디를 읽을지만 적습니다.

   복사해서 써도 되는 요청

   지금 확인한 상세 절차 중 매번 읽을 필요가 없는 내용과, 필요할 때 찾아갈 문서 위치를 나눠서 표로 정리해줘.

   정상이라면 규칙 본문은 짧아지고, 필요할 때 열 문서의 위치가 남습니다.

4. 04

   완료를 눈으로 확인할 수 있게 쓰기

   왜 하나요? “다 됐습니다”라는 말 대신 확인 가능한 신호를 만듭니다.

   할 일 명령, 화면, 파일, 비교 결과 중 지금 실제로 확인할 수 있는 것을 적습니다.

   복사해서 써도 되는 요청

   이 작업이 끝났다고 말하기 전에 사람이 확인해야 하는 신호를 3개 제안해줘. 아직 검사 방법이 없으면 없다고 써줘.

   정상이라면 “충분히 좋다”가 아니라 “이 명령이 통과하고 이 결과가 보인다”로 바뀝니다.

02 · $to-spec

합의한 대화를 명세로 바꾸기

$to-spec은 새 아이디어를 대신 만들어주는 명령이 아닙니다. W1에서 정한 내용을 구현 전에 다시 읽기 쉬운 문서로 묶는 단계입니다.

1. 01

   W1 문서와 프로젝트를 먼저 읽히기

   왜 하나요? 명세가 기억이나 일반론이 아니라 실제 프로젝트에 근거하도록 합니다.

   할 일 W1에서 만든 메모, 자주 쓰는 용어 목록, 결정 기록(ADR), 현재 프로젝트 구조를 먼저 확인하게 합니다.

   복사해서 써도 되는 요청

   먼저 W1에서 만든 문서와 현재 프로젝트 구조를 읽어줘. 문서에 없는 요구사항은 만들지 말고 미결정으로 표시해줘.

   정상이라면 AI가 읽은 자료와 아직 모르는 부분을 구분해 말합니다.

2. 02

   명세 초안 만들기

   왜 하나요? 대화를 문제와 사용자 행동 중심의 문서로 바꿉니다.

   할 일 문제, 해결책, 사용자 스토리, 구현 결정, 테스트 결정, 제외 범위를 작성하게 합니다.

   복사해서 써도 되는 요청

   $to-spec을 실행해 W1 합의만으로 초안을 만들어줘. 추측한 내용은 넣지 말고 추가 메모(Further Notes)에 남겨줘.

   정상이라면 읽는 사람이 “누가 무엇을 해서 어떤 결과를 얻는가”를 알 수 있습니다.

3. 03

   사람이 명세를 고치고 승인하기

   왜 하나요? AI가 그럴듯하게 채운 내용을 팀의 약속으로 착각하지 않게 합니다.

   할 일 다음 세 질문으로 문장을 직접 확인하고, 맞지 않는 부분을 고칩니다.

   정상이라면 ① 실제로 필요한 문제인가? ② 사용자가 확인할 결과가 있는가? ③ 문서에 없는 사실을 AI가 만들어내지 않았는가?

   TIP · 명세를 게시하기 전에는 항상 사람이 승인합니다.

03 · 다음 단계

$to-tickets는 왜 다음 주에 배우나요?

Ticket은 명세를 실제로 만들 수 있는 작은 작업으로 나누는 문서입니다. 지금은 개념만 보고, W3에서 직접 쪼갭니다.

• 한 티켓을 끝내면 혼자서도 결과를 보여줄 수 있어야 합니다.
• 다른 티켓이 끝나야 시작할 수 있을 때만 Blocked by로 연결합니다.
• “프론트 작업”, “백엔드 작업”처럼 기술별로 자르지 않고 사용자 결과가 끝까지 이어지게 자릅니다.