async-suspense-boundaries — правило для Claude Code
Правило async-suspense-boundaries направляет Claude Code выносить загрузку данных в отдельные компоненты с Suspense, чтобы каркас страницы рендерился без задержек.
MIT ★ 7 191 обновлён 2026-10-24
.claude/rules/async-suspense-boundaries.mdЧто делает async-suspense-boundaries
Правило инструктирует модель не блокировать разметку страницы через await в родительском компоненте. Вместо ожидания данных на верхнем уровне агент оборачивает асинхронные блоки в границы Suspense, отдавая сайдбар, шапку и футер сразу.
В описании даны два базовых паттерна: перенос await в дочерний компонент вроде DataDisplay и передача неразрешённого промиса через пропсы сразу нескольким компонентам с распаковкой через хук use. Второй вариант предотвращает повторные запросы, если данные нужны двум соседним блокам.
Шаблон ускоряет первую отрисовку, но повышает риск сдвига макета (layout shift) при появлении контента. Для критичных к поисковой оптимизации блоков на первом экране и быстрых легковесных запросов правило советует отказаться от Suspense.
Какие задачи решает
- ускорить первичную отрисовку страницы при долгих сетевых запросах
- изолировать блокирующий
awaitвнутри дочерних компонентов интерфейса - разделить один промис между несколькими компонентами через хук
use - предотвратить задержку шапки и навигации из-за медленного API
Примеры запросов агенту
- Отрефактори
Page.tsxс использованием Suspense, чтобы шапка и футер не ждали загрузки данных - Переделай компонент профиля так, чтобы промис
fetchData()читался черезuse()в дочерних блоках - Проверь разметку каталога и вынеси долгие сетевые вызовы под границы Suspense
Как установить async-suspense-boundaries
Вручную: положить файлы
.claude/rules/async-suspense-boundaries.mdПоле paths во frontmatter ограничивает файлы
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/async-suspense-boundaries.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/async-suspense-boundaries.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/async-suspense-boundaries.mdВручную: положить файлы
.clinerules/async-suspense-boundaries.mdПо шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать
Вопросы об async-suspense-boundaries
Как установить async-suspense-boundaries в Claude Code?
Сохраните текст правила в корень проекта по пути .claude/rules/async-suspense-boundaries.md.
Что делает правило async-suspense-boundaries?
Оно запрещает блокировать общую разметку через await на верхнем уровне и требует выносить компоненты с загрузкой в Suspense с фолбэками.
Когда не стоит применять этот паттерн?
Паттерн не подходит, когда данные влияют на геометрию родительской сетки, контент критичен для поисковиков на первом экране или запрос отрабатывает слишком быстро для накладных расходов Suspense.
Исходный текст
async-suspense-boundaries.md · MIT
---
title: Strategic Suspense Boundaries
impact: HIGH
impactDescription: faster initial paint
tags: async, suspense, streaming, layout-shift
---
## Strategic Suspense Boundaries
Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
**Incorrect (wrapper blocked by data fetching):**
```tsx
async function Page() {
const data = await fetchData() // Blocks entire page
return (
<div>
<div>Sidebar</div>
<div>Header</div>
<div>
<DataDisplay data={data} />
</div>
<div>Footer</div>
</div>
)
}
```
The entire layout waits for data even though only the middle section needs it.
**Correct (wrapper shows immediately, data streams in):**
```tsx
function Page() {
return (
<div>
<div>Sidebar</div>
<div>Header</div>
<div>
<Suspense fallback={<Skeleton />}>
<DataDisplay />
</Suspense>
</div>
<div>Footer</div>
</div>
)
}
async function DataDisplay() {
const data = await fetchData() // Only blocks this component
return <div>{data.content}</div>
}
```
Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
**Alternative (share promise across components):**
```tsx
function Page() {
// Start fetch immediately, but don't await
const dataPromise = fetchData()
return (
<div>
<div>Sidebar</div>
<div>Header</div>
<Suspense fallback={<Skeleton />}>
<DataDisplay dataPromise={dataPromise} />
<DataSummary dataPromise={dataPromise} />
</Suspense>
<div>Footer</div>
</div>
)
}
function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
const data = use(dataPromise) // Unwraps the promise
return <div>{data.content}</div>
}
function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
const data = use(dataPromise) // Reuses the same promise
return <div>{data.summary}</div>
}
```
Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
**When NOT to use this pattern:**
- Critical data needed for layout decisions (affects positioning)
- SEO-critical content above the fold
- Small, fast queries where suspense overhead isn't worth it
- When you want to avoid layout shift (loading → content jump)
**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
© tech-leads-club · MIT · tech-leads-club/agent-skills