Recipes

전체 가이드를 다시 읽지 않아도 현재 막힌 지점에 맞는 짧은 절차를 골라 쓸 수 있습니다. Recipe는 정답 코드를 제공하는 대신 언제 쓰는가 → 준비할 것 → 실행 순서 → 확인 근거 → 멈출 때를 분명히 합니다.

1. 모호한 요청을 작업 브리프로 바꾸기

언제: 요청은 있지만 완료 기준이 보이지 않을 때

1. 사용자가 경험할 상태 변화를 한 문장으로 적습니다.
2. 유지할 계약과 건드리지 않을 범위를 적습니다.
3. 성공, 실패, 재시도 상태를 나눕니다.
4. 각 조건을 확인할 자동 검사 또는 실제 동작을 연결합니다.
5. 답이 필요한 판단은 질문으로 남깁니다.

확인 근거: 처음 보는 사람이 각 조건의 완료 여부를 예/아니오로 판단할 수 있습니다.

2. 최소 컨텍스트 팩 만들기

언제: 저장소가 크거나 서로 다른 문서가 같은 사실을 말할 때

1. 저장소 지침과 변경 상태를 확인합니다.
2. 사용자 동작에서 코드 호출 경로를 따라갑니다.
3. 규칙, 구현, 테스트, 공식 문서의 권위를 구분합니다.
4. 파일마다 지금 읽어야 하는 이유를 적습니다.
5. 비밀값, 실제 사용자 데이터, 관련 없는 기록을 제외합니다.

확인 근거: 관련 파일과 권위 있는 출처, 아직 모르는 점을 한 화면에서 설명할 수 있습니다.

3. 단일 실행과 병렬 작업 고르기

언제: 여러 작업자를 쓰면 빠를지 판단하기 어려울 때

• 같은 코드 경계를 따라가며 판단해야 하면 한 실행으로 유지합니다.
• 서로 다른 출처 조사, 테스트 분석, 접근성 검토처럼 결과가 독립적이면 병렬로 나눕니다.
• 같은 파일을 동시에 수정해야 한다면 병렬화하지 않습니다.
• 각 작업의 입력, 산출물, 검증, 합류 지점을 먼저 적습니다.

멈출 때: 파일이나 판단 경계가 겹쳐 병합 비용이 예상 절약 시간보다 커지면 단일 실행으로 돌아갑니다.

4. 실패한 테스트에서 다음 행동 정하기

언제: 변경 뒤 검사가 실패했거나 같은 수정이 반복될 때

1. 실패를 제품 코드, 테스트 기대값, 환경, 요구의 모호함으로 우선 분류합니다.
2. 변경 전에도 발생했는지 기준점 결과와 비교합니다.
3. 실패를 설명하는 가장 작은 가설을 세웁니다.
4. 가설 하나만 확인하는 최소 변경이나 진단을 실행합니다.
5. 새 증거가 다음 행동을 바꾸지 않으면 반복을 멈춥니다.

확인 근거: 다음 변경이 어떤 관찰에서 나왔는지 한 문장으로 연결됩니다.

5. UI 변경을 브라우저와 키보드로 검증하기

언제: 레이아웃, 반응형 동작, 폼 상태, 메뉴를 바꿨을 때

1. 실제 빌드 산출물을 로컬 서버로 엽니다.
2. 모바일과 데스크톱 대표 폭에서 핵심 경로를 봅니다.
3. Tab, Enter, Space, Escape로 조작합니다.
4. 포커스 표시, 메뉴 닫힘 후 포커스 복귀, 스크롤 잠금을 확인합니다.
5. 로딩, 빈 상태, 실패, 재시도를 확인합니다.
6. 콘솔 오류와 네트워크 실패를 확인합니다.

확인 근거: 스크린샷뿐 아니라 조작 순서와 관찰한 결과가 남아 있습니다.

6. 안전한 인수인계와 릴리스 카드 작성하기

언제: 다른 사람이 작업을 이어가거나 배포 승인을 받아야 할 때

결과와 변경 위치:
실행한 검증과 결과:
남은 위험 또는 미결정:
승인 조건:
배포 뒤 확인할 경로와 신호:
롤백 조건과 방법:

확인 근거: 대화 기록 없이도 다음 사람이 검증을 재실행하고 승인 여부를 판단할 수 있습니다.

프로젝트의 실제 저장소 규칙은 언제나 Recipe보다 우선합니다. 절차가 맞지 않으면 억지로 적용하지 말고 관련 단계 또는 Reference로 돌아갑니다.