XeroBis/website

계획 및 문서화

이유

"cards 포팅"이나 "portfolio에 태그 추가" 같은 요청은 최종 결정처럼 보이지만, 대개 숨겨진 선택지(지금 얼마나 구현할지, 이전 레포에서 무엇을 버리거나 바꿀지, 어떤 스키마가 데이터를 소유할지, @shared에 무엇을 넣을지)를 남겨둡니다. 즉시 구현하면 잘못된 작업, 재작업, 또는 이미 documentation/decisions.md에 기록된 선택에서 벗어날 위험이 있습니다. 먼저 질문함으로써 문서(그리고 이후의 코드)가 사용자가 실제로 원하는 것을 정확히 기록하도록 보장합니다.

적용 시점

documentation/에서 추적하는 내용을 변경하는 모든 요청: 기능 또는 사용자 동작, 스키마/테이블/컬럼/비즈니스 규칙, 기술 또는 라이브러리 선택, 폴더/아키텍처 구조, migration-plan.md의 단계. 작고 완전히 명시된 수정(오타 수정, 레이블 이름을 정확히 X로 변경)은 인터뷰가 필요하지 않습니다. 실제로 얼마나 모호한지 판단하세요.

단계

1. 질문하기 전에 읽기. 요청과 관련된 documentation/*.md 섹션(및 관련 코드)을 훑어보세요. 포팅할 때는 이전 레포의 자체 문서(../<repo>/documentation/, ../<repo>/CLAUDE.md)와 포팅 대상 코드도 읽으세요. 이미 답변된 내용을 질문하지 마세요. 그것들을 질문의 기준선으로 사용하세요.

2. AskUserQuestion으로 명확하게 질문하기. 하나의 광범위한 질문보다 여러 개의 작고 구체적인 질문을 선호하세요. 이 레포에 적합한 질문 대상:

   • 지금 vs. 나중에 얼마나 구현할지;
   • 포팅 시: 이전 앱에서 무엇을 그대로 유지, 변경, 또는 제거할지(이전 동작이 자동으로 원하는 것은 아님);
   • 새 테이블을 소유할 스키마(앱 자체 스키마 또는 모든 앱이 필요하면 core);
   • 특정 부분이 하나의 앱에 속하는지 아니면 @shared / 공유 백엔드 모듈에 속하는지;
   • features.md가 기록해야 할 UX 세부 사항 및 새 데이터의 형태.

   각 질문에 권장 기본값을 제공하여 사용자가 빠르게 진행할 수 있게 하세요.

3. 사용자가 되돌려준 범위를 정확히 존중하기. 사용자가 "문서만" 또는 "X만, Y는 안 함"으로 범위를 좁히면, 나중에 범위를 확장하기 전에 다시 확인하세요.

4. 결정 단계와 동시에 문서 업데이트하기. CLAUDE.md의 테이블에 따라 라우팅:

   • 폴더 구조, 환경, 포트, 요청 흐름 → architecture.md
   • 스키마, 테이블, 컬럼, 관계, 비즈니스 규칙 → data-model.md, 해당 스키마 섹션 아래
   • 기술/라이브러리/아키텍처 선택 → decisions.md: 선택한 내용, 무엇을 대신 선택했는지, 그 이유를 날짜와 함께 해당 파일 스타일에 맞게 기록
   • 사용자 동작, 검증 규칙 → features.md, 해당 앱 섹션 아래
   • 연기되거나 제외되거나 아직 가능성일 뿐인 사항 → ideas.md
   • 포팅 진행 상황 → migration-plan.md 상태 열
   • 프로덕션 runbook 변경사항 → deployment.md

5. 해결된 아이디어는 ideas.md에서 제거하기. 변경으로 인해 ideas.md 항목이 실제 결정이 되면 해당 항목을 그대로 두지 말고 제거하거나 다시 작성하세요.