Дом

Skill

Производительность и рабочий процесс

read-the-damn-docs

BuilderIO/skills

Обязательно проводит поиск в Интернете и изучает официальную документацию перед внедрением, интеграцией или отладкой сторонних API, библиотек и сервисов, чтобы обеспечить точность и избежать догадок.

...Расширить все

Обновлено время 6 сентября 2026 г.

# documentation # debugging # web search # api reference # best practices # third party apis

Читайте эти чертовы документы

Не пытайтесь угадать, где в авторитетной документации можно найти ответ на вопрос. Самый распространенный правильный подход — найти в интернете актуальную официальную документацию, открыть соответствующие страницы и прочитать их перед началом программирования. Что касается API, версий, поведения провайдеров, настроек, ограничений, хуков жизненного цикла или потоков, связанных с безопасностью, основывайте ответ на том, что действительно сказано в документации.

Поводы для «документации прежде всего»

Прочитайте документацию, прежде чем продолжать, если выполняется любое из следующих условий:

Пользователь просит «последнюю», «актуальную», «официальную», «поддерживаемую», «лучшую практику», «рекомендуемую», «сегодняшнюю», «текущую» информацию или просит «поискать».
Необходимая документация ещё не находится в репозитории и не предоставлена пользователем. Ищите официальную документацию в Интернете, а не полагайтесь на то, что информация в модели актуальна.
Задача предполагает добавление, обновление, настройку или импорт пакета, SDK, фреймворка, плагина, CLI, модели, облачного ресурса или интеграции с поставщиком.
API быстро меняется или чувствителен к версиям: SDK для ИИ, API OpenAI/Anthropic/Google, Next.js, React, Tailwind, Vite, Nitro, Drizzle, Prisma, Stripe, GitHub, Slack, Notion, API браузеров, платформы развертывания, библиотеки аутентификации и т. п.
Реализация зависит от аутентификации, областей действия OAuth, разрешений, секретных данных, вебхуков, биллинга, платежей, персональных данных, шифрования, хранения данных, миграций, повторных попыток, ограничений по частоте запросов, квот, кэширования, развертываний или соответствия нормативным требованиям.
Ошибка может указывать на устаревание, неизвестные параметры, отсутствующие экспорты, неверную конфигурацию, неподдерживаемые поля, измененные значения по умолчанию или несовпадение версий.
Репозиторий содержит локальную документацию, ADR, сгенерированные схемы, спецификации OpenAPI, реестры маршрутов/действий, документацию по системе дизайна или файлы README на уровне пакетов, которые могут определять контракт.
Отменить этот выбор обходится дорого: публичные форматы передачи данных, схема базы данных, стратегия миграции, постоянные идентификаторы, имена событий, поведение, видимое клиенту, или внешние контракты автоматизации.
Вы ловите себя на том, что собираетесь написать «обычно», «вероятно», «я думаю», «на память» или скопировать код из памяти модели для внешнего API.

Что считается документацией

Используйте самый авторитетный из доступных источников:

документацию локального репозитория, спецификации, ADR, схемы, сгенерированные типы, файлы README пакетов и тесты для поведения, специфичного для проекта.
Официальную документацию по продукту, справочники по API, руководства по миграции, журналы изменений, примечания к выпуску и исходный код/типы SDK для поведения сторонних компонентов. Найдите их с помощью веб- поиска, если у вас ещё нет точного URL-адреса.
Метаданные реестра пакетов для версий. Перед добавлением зависимости запустите npm view version, pnpm view versionили его эквивалент в экосистеме , а затем ознакомьтесь с документацией по этой основной версии.
Исходный код или определения типов, если официальная документация неполна. Рассматривайте это как доказательство, а не как слухи.

Избегайте использования Stack Overflow, старых записей в блогах, случайных фрагментов кода и собственной памяти в качестве основного источника, если существует официальная документация. Используйте источники сообщества только для отладки симптомов после того, как станет известен авторитетный контракт.

Требуемый рабочий процесс

Определите точную область: имя пакета, установленную версию, целевую версию, конечную точку поставщика, команду CLI, файл конфигурации, локальный хелпер, схему или функцию продукта.
Проведите поиск в Интернете по текущей официальной документации, если соответствующая документация уже не находится локально или пользователь не предоставил URL-адрес. Используйте целевой поиск, например official docs, migration guide, или API reference.
Откройте и прочитайте документацию, наиболее близкую к данному аспекту. Отдавайте предпочтение сначала локальной документации для внутреннего кода, а затем официальной документации исходного проекта. Для новых пакетов проверьте последнюю версию перед написанием импортов, конфигурации или команд установки.
Извлеките несколько фактов, необходимых для выполнения задачи: названия опций, импорты, правила жизненного цикла, поведение по умолчанию, изменения, нарушающие совместимость, ограничения, разрешения и примеры для текущей основной версии.
Реализуйте или ответьте, используя эти факты. Если документация противоречит существующему коду, проверьте путь локального кода и укажите несоответствие.
Проверьте с помощью минимально необходимой проверки: проверка типов, тесты, сборка, пробный запуск из командной строки, валидация схемы API или локальное воспроизведение.
В окончательном ответе укажите документацию или локальные файлы, к которым вы обращались, если эти сведения влияют на рекомендацию или реализацию.

Примеры, которые обязательно должны привести к созданию документации

«Добавьте Tailwind в это приложение». Перед созданием конфигурационных файлов или использованием старой настройки PostCSS проверьте текущую основную версию Tailwind и документацию по установке в Интернете.
«Используйте AI SDK для потоковой передачи ответов». Проверьте текущую версию AI SDK, импорты, имена пакетов провайдеров, вспомогательные функции потоковой передачи и примеры для сервера/среды выполнения в официальной документации.
«Подключите веб-хуки Stripe». Перед началом программирования ознакомьтесь с текущей документацией Stripe по проверке подписей, повторным попыткам событий, секретным ключам конечных точек и разбору тела запроса в фреймворке.
«Исправьте эту ошибку кэширования в Next.js». Ознакомьтесь с документацией по установленной версии Next.js и режиму маршрутизатора, прежде чем делать предположения о семантике очистки кэша.
«Добавьте миграции Drizzle». Перед генерацией файлов ознакомьтесь с актуальной документацией по набору Drizzle и существующими конвенциями миграции в репозитории.
«Создать GitHub Action». Ознакомьтесь с официальной документацией по синтаксису и правам доступа Actions, особенно в отношении pull_request, workflow_runOIDC, токенов и артефактов.
«Почему этот поток OAuth завершается сбоем?» Перед изменением кода ознакомьтесь с документацией провайдера по областям доступа, URI перенаправления, PKCE, обновлению токенов и проверке приложений.
«Используйте систему планов/комментариев/действий этого репозитория». Ознакомьтесь с локальной документацией, реестрами маршрутов/действий, схемами и тестами, прежде чем придумывать конечные точки или свойства.
«Обновите Vite/Nitro/React». Перед тем как редактировать конфигурацию или импорты, ознакомьтесь с руководством по миграции, чтобы узнать точную целевую версию.
«Какую модель нам использовать?» Перед тем как давать рекомендации, ознакомьтесь с актуальной документацией по моделям провайдеров, страницами с ценами и лимитами, а также примерами из SDK.

Когда достаточно быстрого просмотра локальных файлов

Не ищите в Интернете информацию по поводу каждого мелкого изменения. Просмотр документации может быть локальным и кратким, если ответ уже есть в репозитории: использование существующих хелперов, близлежащие тесты, типизированные интерфейсы, сгенерированные клиенты, ADR или файлы README пакетов. Но если задача зависит от внешнего инструмента, пакета, провайдера или текущего поведения продукта, поиск в Интернете обычно является правильным первым шагом. В случае тривиального синтаксиса языка, исправления опечаток, форматирования или автономного кода без внешних контрактов действуйте как обычно.

Если документация недоступна

Если доступ к сети, авторизация или отсутствие локальных файлов мешают прочитать документацию, четко укажите это, прежде чем полагаться на память. Сузьте область неопределённости, изучите исходный код или типы, если они доступны, и избегайте представления результата как подтверждённого и актуального.

Посмотреть на GitHub

---
name: read-the-damn-docs
description: Forces web searches and reading of official docs before implementing, integrating, or debugging third-party APIs, libraries, and services to ensure accuracy and avoid guesswork.
---

# Read The Damn Docs

Do not guess where authoritative docs can answer the question. The most common
right move is to web-search for the current official docs, open the relevant
pages, and read them before coding. For APIs, versions, provider behavior,
config, limits, lifecycle hooks, or security-sensitive flows, ground the answer
in what the docs actually say.

## Docs-First Triggers

Read docs before proceeding when any of these are true:

- The user asks for "latest", "current", "official", "supported", "best
  practice", "recommended", "today", "now", or "look it up".
- The needed docs are not already in the repo or supplied by the user. Search
  the web for the official docs rather than hoping model memory is current.
- The task adds, upgrades, configures, or imports a package, SDK, framework,
  plugin, CLI, model, cloud resource, or provider integration.
- The API is fast-moving or version-sensitive: AI SDKs, OpenAI/Anthropic/Google
  APIs, Next.js, React, Tailwind, Vite, Nitro, Drizzle, Prisma, Stripe, GitHub,
  Slack, Notion, browser APIs, deployment platforms, auth libraries, and similar.
- The implementation depends on auth, OAuth scopes, permissions, secrets,
  webhooks, billing, payments, PII, encryption, data retention, migrations,
  retries, rate limits, quotas, caching, deploys, or compliance.
- An error mentions deprecation, unknown options, missing exports, invalid
  config, unsupported fields, changed defaults, or version mismatch.
- A repo has local docs, ADRs, generated schemas, OpenAPI specs, route/action
  registries, design-system docs, or package-level READMEs that could define the
  contract.
- The choice is expensive to reverse: public wire formats, database schema,
  migration strategy, persistent IDs, event names, customer-visible behavior, or
  external automation contracts.
- You catch yourself about to write "usually", "probably", "I think", "from
  memory", or code copied from model memory for an external API.

## What Counts As Docs

Use the most authoritative source available:

- Local repo docs, specs, ADRs, schemas, generated types, package READMEs, and
  tests for project-specific behavior.
- Official product docs, API references, migration guides, changelogs, release
  notes, and SDK source/types for third-party behavior. Find these with web
  search when you do not already have the exact URL.
- Package registry metadata for versions. Before adding a dependency, run
  `npm view <pkg> version`, `pnpm view <pkg> version`, or the ecosystem
  equivalent, then read the docs for that major version.
- Source code or type definitions when official docs are incomplete. Treat this
  as evidence, not folklore.

Avoid Stack Overflow, old blog posts, random snippets, and memory as the primary
source when official docs exist. Use community sources only to debug symptoms
after the authoritative contract is known.

## Required Workflow

1. Identify the exact surface: package name, installed version, target version,
   provider endpoint, CLI command, config file, local helper, schema, or product
   feature.
2. Search the web for the current official docs unless the relevant docs are
   already local or the user supplied a URL. Use targeted searches such as
   `<product> <feature> official docs`, `<package> migration guide`, or
   `<provider> API reference`.
3. Open and read the docs closest to that surface. Prefer local docs first for
   internal code, then official upstream docs. For new packages, verify the
   latest version before writing imports, config, or install commands.
4. Extract the few facts needed for the task: option names, imports, lifecycle
   rules, default behavior, breaking changes, limits, permissions, and examples
   for the current major version.
5. Implement or answer using those facts. If the docs conflict with existing
   code, inspect the local code path and call out the discrepancy.
6. Verify with the smallest useful check: typecheck, tests, build, CLI dry run,
   API schema validation, or a local reproduction.
7. In the final answer, name the docs or local files consulted when that
   evidence affects the recommendation or implementation.

## Examples That Must Trigger Docs

- "Add Tailwind to this app." Check the current Tailwind major and its install
  docs from the web before creating config files or assuming old PostCSS setup.
- "Use the AI SDK to stream responses." Verify the current AI SDK major,
  imports, provider package names, streaming helpers, and server/runtime
  examples from official docs.
- "Wire up Stripe webhooks." Read Stripe's current signature verification,
  event retry, endpoint secret, and framework body-parsing docs before coding.
- "Fix this Next.js caching bug." Read the docs for the installed Next.js major
  and router mode before assuming cache invalidation semantics.
- "Add Drizzle migrations." Read the current Drizzle kit docs and existing repo
  migration conventions before generating files.
- "Create a GitHub Action." Read official Actions syntax and permissions docs,
  especially for `pull_request`, `workflow_run`, OIDC, tokens, and artifacts.
- "Why does this OAuth flow fail?" Read the provider's scopes, redirect URI,
  PKCE, token refresh, and app verification docs before changing code.
- "Use this repo's plan/comment/action system." Read local docs, route/action
  registries, schemas, and tests before inventing endpoints or props.
- "Upgrade Vite/Nitro/React." Read the migration guide for the exact target
  major before editing config or imports.
- "What model should we use?" Read current provider model docs, pricing/limits
  pages, and SDK examples before recommending.

## When A Quick Local Read Is Enough

Do not browse the web for every tiny edit. A docs pass can be local and brief
when the answer is already in the repo: existing helper usage, nearby tests,
typed interfaces, generated clients, ADRs, or package READMEs. But if the task
depends on an external tool, package, provider, or current product behavior, web
search is usually the right first step. For trivial language syntax, typo fixes,
formatting, or self-contained code with no external contract, proceed normally.

## If Docs Are Unavailable

If network access, auth, or missing local files prevents reading the docs, say
that plainly before relying on memory. Narrow the uncertainty, inspect source or
types if available, and avoid presenting the result as confirmed-current.