BuilderIO/read-the-damn-docs

Read The Damn Docs (문서를 제대로 읽으세요) - 한국어 번역

권위 있는 문서가 답을 알려줄 수 있는데 추측하지 마세요. 가장 일반적이고 올바른 방법은 현재 공식 문서를 웹 검색하여 관련 페이지를 열고, 코딩하기 전에 읽는 것입니다. API, 버전, 프로바이더 동작, 설정, 제한, 라이프사이클 훅, 또는 보안에 민감한 흐름의 경우, 답변을 문서에 실제로 명시된 내용에 근거하세요.

문서 우선 트리거

다음 중 하나라도 해당되면 진행 전에 문서를 읽으세요:

• 사용자가 "최신", "현재", "공식", "지원됨", "모범 사례", "권장", "오늘", "지금", 또는 "찾아봐"라고 요청합니다.
• 필요한 문서가 이미 저장소나 사용자에 의해 제공되지 않았습니다. 모델 메모리가 최신이라고 기대하기보다 웹에서 공식 문서를 검색하세요.
• 작업에 패키지, SDK, 프레임워크, 플러그인, CLI, 모델, 클라우드 리소스 또는 프로바이더 통합을 추가, 업그레이드, 설정 또는 임포트합니다.
• API가 빠르게 변하거나 버전에 민감합니다: AI SDK, OpenAI/Anthropic/Google API, Next.js, React, Tailwind, Vite, Nitro, Drizzle, Prisma, Stripe, GitHub, Slack, Notion, 브라우저 API, 배포 플랫폼, 인증 라이브러리 등.
• 구현이 인증, OAuth 범위, 권한, 시크릿, 웹훅, 결제, 지불, PII, 암호화, 데이터 보존, 마이그레이션, 재시도, 속도 제한, 할당량, 캐싱, 배포 또는 규정 준수에 의존합니다.
• 오류 메시지에 지원 중단, 알 수 없는 옵션, 누락된 익스포트, 잘못된 설정, 지원되지 않는 필드, 변경된 기본값 또는 버전 불일치가 언급됩니다.
• 저장소에 계약을 정의할 수 있는 로컬 문서, ADR, 생성된 스키마, OpenAPI 스펙, 라우트/액션 레지스트리, 디자인 시스템 문서 또는 패키지 수준의 README가 있습니다.
• 결정을 되돌리기 어려운 경우입니다: 공개 와이어 형식, 데이터베이스 스키마, 마이그레이션 전략, 영구 ID, 이벤트 이름, 고객에게 보이는 동작 또는 외부 자동화 계약.
• 외부 API에 대해 "보통", "아마", "내 생각엔", "기억에 의존하여"라고 쓰려고 하거나, 모델 메모리에서 복사한 코드를 작성하려는 순간을 발견합니다.

문서로 간주되는 것

사용 가능한 가장 권위 있는 출처를 사용하세요:

• 프로젝트별 동작에 대한 로컬 저장소 문서, 스펙, ADR, 스키마, 생성된 타입, 패키지 README 및 테스트.
• 타사 동작에 대한 공식 제품 문서, API 레퍼런스, 마이그레이션 가이드, 변경 로그, 릴리스 노트 및 SDK 소스/타입. 정확한 URL을 이미 알고 있지 않다면 웹 검색으로 찾으세요.
• 버전에 대한 패키지 레지스트리 메타데이터. 의존성을 추가하기 전에 npm view <pkg> version, pnpm view <pkg> version 또는 해당 생태계의 동등한 명령어를 실행한 다음, 해당 메이저 버전의 문서를 읽으세요.
• 공식 문서가 불완전한 경우 소스 코드 또는 타입 정의. 이것을 증거로 취급하고, 전설로 취급하지 마세요.

공식 문서가 존재하는 경우 Stack Overflow, 오래된 블로그 게시물, 임의의 스니펫 및 메모리를 주요 출처로 사용하지 마세요. 권위 있는 계약을 파악한 후에만 커뮤니티 출처를 증상 디버깅에 사용하세요.

필수 워크플로우

1. 정확한 대상을 식별하세요: 패키지 이름, 설치된 버전, 대상 버전, 프로바이더 엔드포인트, CLI 명령어, 설정 파일, 로컬 헬퍼, 스키마 또는 제품 기능.
2. 관련 문서가 이미 로컬에 있거나 사용자가 URL을 제공하지 않은 경우, 현재 공식 문서를 웹에서 검색하세요. <제품> <기능> 공식 문서, <패키지> 마이그레이션 가이드 또는 <프로바이더> API 레퍼런스와 같은 대상 검색을 사용하세요.
3. 해당 대상에 가장 가까운 문서를 열고 읽으세요. 내부 코드의 경우 로컬 문서를 먼저 선호하고, 그 다음 공식 업스트림 문서를 선호하세요. 새 패키지의 경우 임포트, 설정 또는 설치 명령어를 작성하기 전에 최신 버전을 확인하세요.
4. 작업에 필요한 몇 가지 사실만 추출하세요: 옵션 이름, 임포트, 라이프사이클 규칙, 기본 동작, 호환성 문제, 제한 사항, 권한 및 현재 메이저 버전에 대한 예제.
5. 해당 사실을 사용하여 구현하거나 답변하세요. 문서가 기존 코드와 충돌하는 경우, 로컬 코드 경로를 검사하고 차이점을 지적하세요.
6. 가장 작은 유용한 확인으로 검증하세요: 타입 검사, 테스트, 빌드, CLI 드라이 런, API 스키마 검증 또는 로컬 재현.
7. 최종 답변에서, 증거가 권장 사항이나 구현에 영향을 미칠 때 참고한 문서나 로컬 파일 이름을 명시하세요.

문서를 트리거해야 하는 예시

• "이 앱에 Tailwind를 추가하세요." 설정 파일을 만들거나 이전 PostCSS 설정을 가정하기 전에 웹에서 현재 Tailwind 메이저와 설치 문서를 확인하세요.
• "AI SDK를 사용하여 스트리밍 응답을 구현하세요." 공식 문서에서 현재 AI SDK 메이저, 임포트, 프로바이더 패키지 이름, 스트리밍 헬퍼 및 서버/런타임 예제를 확인하세요.
• "Stripe 웹훅을 연결하세요." 코딩하기 전에 Stripe의 현재 서명 확인, 이벤트 재시도, 엔드포인트 시크릿 및 프레임워크 본문 파싱 문서를 읽으세요.
• "이 Next.js 캐싱 버그를 수정하세요." 캐시 무효화 의미를 가정하기 전에 설치된 Next.js 메이저 및 라우터 모드에 대한 문서를 읽으세요.
• "Drizzle 마이그레이션을 추가하세요." 파일을 생성하기 전에 현재 Drizzle 키트 문서와 기존 저장소 마이그레이션 규칙을 읽으세요.
• "GitHub Action을 만드세요." 특히 pull_request, workflow_run, OIDC, 토큰 및 아티팩트에 대한 공식 Actions 구문 및 권한 문서를 읽으세요.
• "이 OAuth 흐름이 왜 실패하나요?" 코드를 변경하기 전에 프로바이더의 범위, 리디렉션 URI, PKCE, 토큰 갱신 및 앱 확인 문서를 읽으세요.
• "이 저장소의 plan/comment/action 시스템을 사용하세요." 엔드포인트나 props를 새로 만들기 전에 로컬 문서, 라우트/액션 레지스트리, 스키마 및 테스트를 읽으세요.
• "Vite/Nitro/React를 업그레이드하세요." 설정이나 임포트를 편집하기 전에 정확한 대상 메이저에 대한 마이그레이션 가이드를 읽으세요.
• "어떤 모델을 사용해야 하나요?" 추천하기 전에 현재 프로바이더 모델 문서, 가격/제한 페이지 및 SDK 예제를 읽으세요.

빠른 로컬 읽기로 충분한 경우

모든 작은 편집에 대해 웹을 탐색하지 마세요. 답변이 이미 저장소에 있는 경우(기존 헬퍼 사용법, 근처 테스트, 타입 인터페이스, 생성된 클라이언트, ADR 또는 패키지 README) 문서 패스는 로컬 및 간단할 수 있습니다. 그러나 작업이 외부 도구, 패키지, 프로바이더 또는 현재 제품 동작에 의존하는 경우, 웹 검색이 일반적으로 올바른 첫 단계입니다. 사소한 언어 구문, 오타 수정, 서식 지정 또는 외부 계약이 없는 자체 포함된 코드의 경우 정상적으로 진행하세요.

문서를 사용할 수 없는 경우

네트워크 액세스, 인증 또는 누락된 로컬 파일로 인해 문서를 읽을 수 없는 경우, 메모리에 의존하기 전에 그 사실을 명확히 말하세요. 불확실성을 좁히고, 가능하면 소스나 타입을 검사하며, 결과를 현재 확인된 것으로 제시하지 마세요.