Перейти до основного вмісту

Частина 1: Налаштуйте файл правил

Агент-кодер приходить у ваш репозиторій як новий інженер у перший робочий день — тільки без можливості ставити запитання. Він робитиме умовиводи. А без будь-яких орієнтирів він помилятиметься передбачувано: неправильний патерн управління станом, неправильне розташування папок, неправильна конвенція тестів, неправильний шлях імпорту.

Файл правил — це документ для онбордингу, який той новий інженер ніколи не мав змоги попросити вас написати. Це найефективніша витрачена година в цьому посібнику, оскільки кожна майбутня взаємодія в проєкті успадковує його.

Чому це працює​

Більшість людей намагаються виправити погані результати AI, складаючи розумніші промпти. Це хибний важіль. Якість результату набагато більше залежить від того, що агент знає про ваш проєкт, ніж від того, як ви формулюєте запит. Файл правил кодує ці знання один раз, і вам не доводиться пояснювати їх знову й знову на кожній сесії.

Файл має різні назви залежно від інструменту — CLAUDE.md, AGENTS.md, GEMINI.md — але зміст відповідає одній ідеї: хто такий агент у цьому репозиторії, що він повинен робити і чого ніколи не повинен робити.

Що туди включати​

Чотири частини. Кожна — коротка й конкретна.

  1. Стек і версії — щоб агент перестав вгадувати, які API існують.
  2. Конвенції — патерни, які ви реально використовуєте, а не загальні найкращі практики.
  3. Жорсткі правила — речі, яких не повинно відбуватися ніколи.
  4. Робочий процес — кроки, яких слід дотримуватися до і після генерації коду.

Реальний приклад​

# CLAUDE.md

## Stack
- Python 3.12, FastAPI, SQLAlchemy 2.0 (async)
- Postgres 16, Alembic for migrations
- pytest + httpx for tests
- uv for dependency management

## Conventions
- Feature folders under `app/features/<name>/`, not layered by type.
- Routes are thin: validation + a single service call. No business logic in routes.
- Services return domain objects; serialization happens in the route layer.
- All DB access goes through repositories. No raw SQL in services.
- Async everywhere. No blocking calls inside request handlers.

## Hard rules
- Never add a dependency that isn't already in pyproject.toml. Ask first.
- Never write secrets, tokens, or connection strings into code or tests.
- No `print()`. Use the configured `structlog` logger.
- Every new endpoint needs a test in the matching `tests/` folder before it's done.
- Run `ruff check` and `pytest` before declaring a task complete.

## Workflow
1. Read the feature's spec or ticket before writing code.
2. Write the test first, then implement until it passes.
3. If a change touches the database schema, stop and flag it for human review.
4. After implementing, confirm ruff and pytest both pass, then summarize what changed.

Зверніть увагу на те, чим це не є: це не промпт і не підручник з FastAPI. Це набір операційних інструкцій, специфічних для цієї кодової бази. Модель-генераліст вже знає FastAPI; чого вона не знає — так це того, що у вашому проєкті роути мають бути тонкими, а ваше правило щодо секретів є абсолютним.

Розвивайте його методом виправлень​

Не намагайтеся написати ідеальний файл одразу. Почніть із десяти рядків і дозвольте реальним збоям навчити вас, що додавати. Цикл простий:

  • Агент робить щось небажане.
  • Ви додаєте одне правило, яке це запобігає.
  • Це більше ніколи не повторюється.

Наприклад, якщо агент постійно вигадує загальний файл utils.py, додайте:

- No catch-all `utils.py`. Helpers live next to the feature that uses them.

Кожне правило дешево додати, і воно окупається на кожному наступному завданні. За кілька тижнів у вас буде файл, який змушує агента поводитися так, ніби він працює над проєктом вже кілька місяців.

Визначайте інструменти теж​

У файлі правил також слід вказати, до яких інструментів агент може звертатися і коли їх використовувати — конкретні внутрішні API, скрипти, схеми баз даних. Однорядковий опис коли викликати інструмент не дає агенту ні ігнорувати його, ні зловживати ним.

## Tools
- `scripts/seed_db.py` — reset local data. Use before running integration tests.
- Internal `billing-api` (OpenAPI at /openapi.json) — never call in tests; mock it.

Архітектура — ваша; агент реалізує​

Одну межу слід тримати чітко: агент добре реалізує архітектуру і погано її обирає. Такі компроміси, як узгодженість проти доступності або «будувати чи купувати», залежать від бізнес-контексту, якого модель не бачить. Приймайте ці рішення самостійно, записуйте їх і дозвольте агенту будувати за ними. Чітка архітектурна нотатка у файлі правил перетворює агента на стабільного виконавця замість імпровізатора.

Налаштуйте власний робочий процес​

  • Створіть файл правил у корені вашого репозиторію відповідно до конвенції іменування вашого інструменту.
  • Напишіть десять рядків: стек, дві-три конвенції, два-три жорсткі правила, короткий робочий процес.
  • Додайте розділ ## Tools із переліком скриптів/API, які агент має і не має використовувати.
  • Упродовж наступного тижня додавайте по одному правилу щоразу, коли агент поводиться неналежно.
  • Закомітьте файл у систему контролю версій, щоб уся команда (і кожна майбутня сесія) мала спільний файл.