Практычныя прытамулкі: як я структурую проекты Claude Code, каб агенты не заплуталіся

Наступныя прыміткі паказваюць практычны падход да тэмы «Як я структурую проекты Claude Code, каб агенты не заплуталіся ў вялікіх кодавых базах». Акцэнт ставяцца на кантракты, перакрычанняі і месца для коду, які можна легка заменіць, а не на мотывацыйныя аспекты. Калі працуеце на стадіі адгляду, спачатку запісайце кантракт: неабяжлівыя даннэ, сігнал успеху і тое, што выканаецца у разе частковага няўспэху. Такі список контролю дапамагае заставаць пазнейшыя змены коду чыстымі. Храніце настройкі парадульна ад коду прыемлівача. Файлы сераўіса, хранальнікі секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць без неабяжлівага чытання всей структуры.

Основная проблема: вікна контэксту быстра запоўняюцца

Контекстальны ўзлаковы проблемы работаюць наякша, калі іх спрыяваць як мерымабельную паверхню. Запісаце адна ідеальная версія, адзін прыклад неудачы і запіс пра атрыбуты, якія трэба вярнуць, прычаму расширэння масштаба. Дакументавайце як успішны, так і вярнучыся шляхы развіцця. Перапрыбуткі, людзкі контроль і обработка некоректных паведамленняў ёсць часткай продукту, а не пасляднім дапрацоўкам. Храніце стан графа ў простым і типаванам формате. Вярнутыя блокі маскуюць, який вузел запісаў канкрэтны поле, і спакшваюць продовжэнне роботы пасля перерываў.

Шаблон 1: Файлы CLAUDE.md у шарах (не адзін вялікі ўзлаковы файл)

Этап Pattern 1 Layered CLAUDE працюе найкраща, калі яго розглядаць як вимерную паверхню. Запісаўце адна «золатая» транскрыпцыя, адин прыклад неудачы і запіс пра відкатанне раней, чым расширваць масштабы. Валіце маленькія, тэставаныя елементы замест велікіх скрыптов. Калі якась цэпочка парадок, неудача должна вказваць на адну адпаведальнасць, а не на заплутаны ланцюг задач. Рэзервавайце стан графа ў простаму і типізаванаму варыянце. Вкладаныя структуры маскуюць інфармацыю пра тое, який вузел запісаў канкрэтны поле, і спакоююць працу пасля перерываў.

monorepo/
  CLAUDE.md                     # repository-wide rules only
  packages/
    api/
      CLAUDE.md                 # API-specific conventions
      .claude/skills/
      src/
    web/
      CLAUDE.md                 # frontend-specific conventions
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 # shared library conventions
      src/

# Repository Structure

This is a monorepo with three packages under packages/:

- packages/api: Node.js REST API with Express, TypeScript, PostgreSQL
- packages/web: React frontend with Vite, TypeScript, TailwindCSS
- packages/shared: shared TypeScript utilities

Run commands from the package directory, not the monorepo root.
Each package has its own tsconfig.json, package.json, and test suite.

# Commit Conventions

- Prefix commits with the package name: "api: fix session timeout"
- One commit per logical change
- Run tests before committing

# API Package

This is the REST API server.

## Commands

- Run tests: `npm test` (uses Vitest)
- Run dev server: `npm run dev` (port 3001)
- Database migrations: `npm run migrate`
- Environment variables: copy `.env.example` to `.env`

## Code Patterns

API routes are in src/routes/. Each route file exports an Express router.
Database queries use Knex in src/db/. Never write raw SQL in route handlers.

## Testing

Tests are in src/__tests__/ mirroring the src/ directory.
Use supertest for HTTP assertions, not raw fetch.
Always wrap database tests in a transaction that rolls back.

Pattern 2: Навыкі для знанняў на запит

Метод «Pattern 2 Skills for stage» працюе найэфектывней, калі яго спрыяваць як мерыемую структуру. Зберагачыце адны ідеальны прыклад роботы, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштабы. Спрыяйце гэтам этапу як кантракту межа вхіднымі даннымі і пераканаленымі выходнымі рэзультатамі. Даўце назвы всім элементам, задаце критэрыя успеху і не падтрымайце частковае завершэння задання без паведамлення. Рэзультаты роботы трэба зберагачыць у простай і типаванай форме. Вярнутыя структуры данных маскуюць інфармацыю пра тое, який вузел запісаў кожны поле, і спакшуюць возможнасць продажчэння роботы пасля перарываў. Метод «Pattern 2 Skills for stage» працюе найэфектывней, калі яго спрыяваць як мерыемую структуру. Зберагачыце адны ідеальны прыклад роботы, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштабы. Канфігурацыю трэба зберагачыць паза кодам прыкладнай програмы. Файлы сэрвеіру, хранільнікі секретных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куда аператары можу аудытаваць іх без неабяжнага чытання всей структуры данных.

# .claude/skills/api-testing/SKILL.md

---
name: api-testing
description: Testing patterns for the API package. Use when writing or modifying tests in packages/api/.
---

## Test Structure

Tests are in `src/__tests__/` mirroring the `src/` directory structure.
Each route file has a corresponding `.test.ts` file.

## Running Tests

- All tests: `npm test`
- Single file: `npm test -- src/__tests__/routes/users.test.ts`
- Watch mode: `npm test -- --watch`

## Test Utilities

- `src/__tests__/helpers/db.ts`: provides `setupTestDb()` and `teardownTestDb()`
- `src/__tests__/helpers/auth.ts`: provides `createTestUser()` and `getAuthToken()`

## Patterns

- Use `supertest` for HTTP assertions, not raw fetch
- Always wrap database tests in a transaction that rolls back
- Mock external services in `src/__tests__/mocks/`

Pattern 3: Падагенты для ізольаванага адкрыцтва

Для падчынных агентаў шаблона 3 на данам этапе неабходна прадзефінаваць вхідныя даны, адпаведальную особу за кожны крок і крэтарыя выходу пры змены коду. Аператары должны магчымае перзапускати крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Неабходна аддзеіставіць дакументацыю як для стандартнага, так і для альтернатывнага падходу. Практыка перапрыбуткі, людзкія пераказы і обработка некоректных паведамленняў є часткай продукту, а не елементамі пазнейшага дапрацоўкі. Неабходна людзкая аправарацыя для тых крокаў, якіе ведуць да выдатка грошаў або змены дадзэнняў у прыемным процесе. Працэс складання коду не є гарантыяй полнай адпаведнасці продукту бізнес-трэбованням.

Use a subagent to investigate how our authentication system handles
session timeout and token refresh. Report back what files are involved
and how the flow works.

Use a subagent to review the session timeout fix for edge cases
and consistency with our existing auth patterns.

Шаблон 4: Блакаванне чытання створанага і прадастоўленага коду

Для блока Патэрн 4, які выконваецца на стадыі «read stage», пярэд тым, як зменіць код, неабходна адзначыць вхідныя даны, адпаведальнага за крок і критэрыя завершэння. Аперацыіям павінна быць можлівасць перзапускаць крок з вядомай точкі контролю, не спрабоўваючы здогадвацца пра схованы стан. Валідзіце маленькія, тэставаныя елементы замест большых скрыптов. Калі крок не выконваецца, прычына неудачы павінна вказываць на адзін конкрэтны элемент, а не на заплутаны ланцюг задач. Заставляйце людзей апраўдваць тыя крокі, якія ведуць да витрачання грошаў або змены данных у прыемнай сістэме. Компіляцыйныя налаштаванні не є гарантыяй полнай адпрацоўкі бізнес-процэса.

# packages/api/.claude/settings.json

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**)",
      "Read(./**/build/**)",
      "Read(./**/*.generated.*)",
      "Read(./vendor/**)"
    ]
  }
}

Патэрн 5: Разрозненыя структуры для шырэйшага выкарыстоўвання

Для стадіі Pattern 5 Sparse worktrees неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крэтыры завершэння пры змяне коду. Аперацыйныя працавікі должны магчымае перайсці цей крок з вядомага пункта контролю без адгадвання захаванага стану. Спрытывайце гэту стадію як кантракт межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, узначыце перакананні на успех і адмовіцеся ад тых падчасовых завершэнняў, калі няма інформацыі. Забезпечыце людскую апраўду для тых крокаў, якія выкарыстоўваюць грошы або зміняюць даны праўеркі. Компіляцыйныя налашчэння не ўзначаюць павнае завершэння бізнес-процесаў. Для стадіі Pattern 5 Sparse worktrees неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крэтыры завершэння пры змяне коду. Аперацыйныя працавікі должны магчымае перайсці цей крок з вядомага пункта контролю без адгадвання захаванага стану. Зберагачыце налашчэнні параду аплікацыйнага коду. Файлы сераўіса, хранільнікі секрэтных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, якое працавікі можу аудытаваць, не чытаючы весь код.

Граф.

# packages/api/.claude/settings.json

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ]
  }
}

Шаблон 6: Плагіні з інтелектам коду заместо сканавання файлаў

Калі працуеце над стадзіяй інтелектам коду згадна з Шаблонам 6, спачатку запісайце умовы викорыстоўвання: неабходныя даны, сігнал успеху і тое, што выканаецца у разе частковага невыпалення. Такі список пераканае вас робіць чыстыя змены ў кодзе пазней. Документавайце як правільны, так і альтернатыўны шляхы виконання. Практыкі перапрыбутку, людзкі контроль і обработка некоректных паведамленняў є частью продукту, а не дадатковыми правкамі пазней. Зявляйце логі з назвай інструмента, хэшам аргументаў, часам затрымкі і рэзультатам кожнага вызову. Без такога следу дэбагаванне можа зайняць гады.

/plugin install typescript-lsp@claude-plugins-official

src/middleware/auth.ts:47
src/routes/users.ts:103
src/__tests__/auth.test.ts:22

Саюзны эфект: ад хаосу да яснасі

Калі працуеце над «Сумарным эфектам з стэйджа», спачатку запісайце умовы кантракту: неабяжлівыя даны, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список контроля дапамагае заліцвачыць змяны ў кодзе па правдзе. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшоў, прычына нявыпання павінна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцужок задач. Зробіце перапактаванне пасля дорогіх крокаў. Програма не павінна зноў стягваць плата за той самы вызов LLM, калі аператар праканае пазнейшы вузел.

Калі выкарыстоўваць кожны патэрн

Калі працюеце над пытаннем «Калі викорыстоўваць кожны этап», спачатку запісайце «контракт»: неабходныя вхідныя даны, сигнал успеху і тое, што выходзіць у разе частковай нявыполненасці. Такі список пераканае ў тым, што пазнейшыя змены коду будуць чыстымі. Спрыймайце гэты этап як контракт межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Дайце назвы артыфактам, задаце правіла пераканання успеху і не падзволяйце частковай нявыполненасці без паведамлення. Зробіце перакананне пасля дорогіх крокаў. Система вярнення не павінна знову ставіць плату за той самы вызов LLM, калі аператар праказвае пазнейшы вузел. Калі працюеце над пытаннем «Калі викорыстоўваць кожны этап», спачатку запісайце «контракт»: неабходныя вхідныя даны, сигнал успеху і тое, што выходзіць у разе частковай нявыполненасці. Такі список пераканае ў тым, што пазнейшыя змены коду будуць чыстымі. Зберагаеце настройкі паза кодам прыемленае. Файлы сераўіса, хранільнікі секрэтных данных і флагі функций павінны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць без неабяжнага чытання всіх элементаў.

Чэк-ліст для аператараў

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

Запісвайце час выконання і вартасьць токеноў або запытанняя разам з функцыйнаімі рэзультатамі. Відразлівае прадставлення вартасцей запобегае неспакоўным рахункам, калі процес пераходзіць з дэмовай среды ў спяльнаваныя сераўеры.

Забезпечыце людзкія атстаўкі для тых крокаў, якія выкарыстоўваюць грошы або зміняюць даны ў працэсе виробніцтва. Компіляцыйныя налашчэння не є падставай для абсалютнага завершэння бізнес-процесу.

Напісце кароткі посоўнік: як зменяць клучы, як спрачыслаць чергу запытанняя, як анулюваць пасляпэўныя зміны.

Зберагачыце налашчэння парадульна ад коду прыкладнага програма. Файлы среды, хранільнікі секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, якое працавнікі можуць пераглядаць, не чытаючы весь код.

Неабяжна людская празначэнне для тых элементаў, якія выдвайнаюць грошы або зменяюць данні праработкі. Працаванне ў часе компілявання не абяжаецца пачынкамі бізнес-процэсаў.

Перш чым пераводзіць стэк, заморажваюць версіі, фіксуюць «золаты» транскрыпты для критычных ліній працы і паверачваюць крокі для адката. У спадзяльных средах патрэбны ліміты частоты, перакананні ў прыналежнасці і чыстае адпаведальнае аб’екта для ротацыі секрэтных дадзенняў. Лепш выбіраць простую надзею на надзейнасць, чым хітрыя експерыментальныя дэманстрацыі.

Запіс для пакета 9ad69a2ebb92: не клаціць ключы прадаўцоў у репазітары, задаць максымальную кантитатыву токенаў на сесію і хаваць транскрыпты праз адно з фіксатываў eval, каб пазнейшыя замены модэляў заставаліся парабяльнымі.

Калі працуеце над першым этапам зміцнення, спачатку запісайте умовы: неабяцковыя даны, сигнал успеху і тое, што выходзіць па частый неякосці. Такі список дапамагае залічваць пазнейшыя змены коду чыста і прозрачна. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшае, неякосць должна вказваць на адзін конкрэтны аспект, а не на заплутаны ланцюг задач.

Дзеянне зміцнення 0/916: вымерыце час выканання, класію памылак і колькасць викорыстоўваных токенав для гэтага пункту, а потым выявіце, чы рашыцца застаўляць змену на адной фіксаванай сэтке пытанняў, а не на адзінственных прыкладах.

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

Дзеянне паўжасткі 1/916: звярніце увагу на час выканання, клас памылкі і колькасць выкарыстоўваных токенаў для гэтага запісу, а пасля, на аднойчынай базе паказаных дадзенняў, а не на індывідуальных прыкладах, выявіце, чы хацяце застаўіць змену.

Этап 0 паўжасткі працюе найэфектывней, калі яго розглядаць як меравальную плошчу. Зафіксаваце адны ідеальны прыклад роботы, адну ситуацыю абвалення і запіс пра вярнэнне да пачатковага стану, перш чым расширваць сферу дзеяння. Канфігурацыю трэба зберагчы параду ад коду прыемлівача; файлы сяродавішча, хранільнікі секрэтных дадзенняў і флагі функцый должны знаходзіцца ў аднам месцы, куда аператары можуць адбавіць аудыт без неабходнасці чытання всей структуры.

Дзеянне паўжасткі 0/935: звярніце увагу на час выканання, клас памылкі і колькасць выкарыстоўваных токенаў для гэтага запісу, а пасля, на аднойчынай базе паказаных дадзенняў, а не на індывідуальных прыкладах, выявіце, чы хацяце застаўіць змену.

Для першага пасэгу з ударожанняя абярання неабходна ўзначэнне вхідных дадзеных, адпаведальнага за шаг і крэтарыяў завершэння працы перад зменым коду. Аперацыйныя працавнікі должны магчымае перадзеўсці шаг з вядомай точкі контролю, не падозрываючы прыхованы стан. Лепш выбіраць маленькія, тэставаныя елементы замест большых скрыптов. Калі шаг не выйшаў, прычына неудачы должна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны процес.

Дзеянне ударожанняя 1/935: зважыце час выконання, класію памылак і колькасць выкорыстоўваных токенаў для гэтага пасэгу, а потым вырашыце, чы робіць змену на адной пазначанай базе пытанняў, а не на адной лічбе прыкладаў.