Практичні поради: Перестаньте стежити за своїм агентом з кодування: створіть систему, якій можете довіряти

Використовуйте цей документ як оновлену версію ідей з книги „Stop Watching Your Coding Agent: Build a System You Can Trust“, орієнтовану на операторів: чіткі етапи, впорядковані блоки коду та примітки з відновлення, які залишаються при передачі обов’язків. Етап Огляду найкраще функціонує, якщо його розглядати як вимірювану основу. Запишіть один ідеальний запис, один випадок збою та примітки щодо скасування змін перед розширенням обсягу роботи. Віддавайте перевагу невеликим, тестованим одиницям коду перед об’ємними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій.

Проблема: ви, ймовірно, все ще виконуєте лише половину роботи

Для поточної стадії проблеми необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Розглядайте цю стадію як контракт між вхідними даними та перевіреними результатами. Призначте назви для результатів роботи, визначте критерії успіху та не допускайте мовчазного часткового завершення. Вимагайте людського схвалення для операцій, які призводять до витрат грошей чи змінюють дані у продакшені. Підключення елементів під час компіляції не є гарантією повності виконання бізнес-завдань.

You: Fix the login bug.
Agent: Done.
You: opens browser
You: It still doesn't work.
Agent: Ah. I found the problem.
You: No, that's not it.
Agent: You're right. I found the REAL problem.
You: sends screenshot
Agent: Ah...

1. Надайте агенту одну команду для позначення „завершено“

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

scripts/verify.sh

#!/usr/bin/env bash
set -euo pipefail

echo "== Python lint =="
uv run ruff check backend

echo "== Python types =="
uv run mypy backend

echo "== Python tests =="
uv run pytest -q

echo "== Frontend lint =="
npm --prefix frontend run lint

echo "== Frontend tests =="
npm --prefix frontend test -- --run

echo "Verification passed."

#!/usr/bin/env bash
set -euo pipefail

echo "== Python lint =="
python -m ruff check backend

echo "== Python types =="
python -m mypy backend

echo "== Python tests =="
python -m pytest -q

echo "== Frontend lint =="
npm --prefix frontend run lint

echo "== Frontend tests =="
npm --prefix frontend test -- --run

echo "Verification passed."

chmod +x scripts/verify.sh

verify:
        ./scripts/verify.sh

make verify

inspect
↓
change code
↓
verify
↓


failure
↓
inspect
↓
change code
↓
verify

2. Щодо багів: вимагайте докази перед виправленням

На етапі виявлення помилок у проекті 2 For слід заздалегідь визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Конфігурацію потрібно тримати окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функціоналу мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь кодовий граф. Необхідно передбачити людське схвалення для операцій, які призводять до витрат грошей чи змінюють дані у продакшені. Підключення елементів під час компіляції не є гарантією повноти бізнес-логіки. На етапі виявлення помилок у проекті 2 For слід заздалегідь визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Краще використовувати невеликі, тестовані одиниці коду замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на складну структуру обробки даних.

def parse_timeout(value: str) -> float:
    if value.endswith("s"):
        return float(value[:-1])

    if value.endswith("m"):
        return float(value[:-1]) * 60

    return float(value)

250ms is interpreted incorrectly.

def test_parse_timeout_milliseconds():
    assert parse_timeout("250ms") == 0.25

uv run pytest tests/test_timeout.py -q

python -m pytest tests/test_timeout.py -q

def parse_timeout(value: str) -> float:
    if value.endswith("ms"):
        return float(value[:-2]) / 1000

    if value.endswith("s"):
        return float(value[:-1])

    if value.endswith("m"):
        return float(value[:-1]) * 60

    return float(value)

reported bug
    ↓
observed failure
    ↓
code change
    ↓
observed success

3. Надайте агенту посібник з інтеграції

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

# Project

FastAPI backend + React frontend.

Python dependencies are managed with uv.

## Important directories

backend/app/api/       HTTP endpoints
backend/app/services/  business logic
frontend/src/features/ feature code
tests/                 backend tests

## Commands

Fast Python tests:

    uv run pytest -q tests/unit

Full verification:

    make verify

Development:

    make dev

## Working rules

Before editing:

1. Reproduce the problem.
2. Inspect the implementation involved.
3. Find similar existing code before creating a new pattern.
4. Identify or add a test.

Before completion:

1. Run relevant tests.
2. Run `make verify`.
3. Inspect `git diff`.
4. Report exactly what was verified.

Fast Python tests:
    python -m pytest -q tests/unit

4. Перетворіть повторювані уроки на навички

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

skills/debug-with-evidence/SKILL.md

# Debug with evidence

Before modifying production code:

1. Capture the exact symptom.
2. Reproduce it.
3. Find the narrowest failing case.
4. Inspect the code actually executed.
5. Form hypotheses only after gathering evidence.
6. Prefer experiments that distinguish competing explanations.
7. Add a regression test when practical.
8. Make the smallest justified fix.
9. Rerun the reproduction.
10. Run full verification.

For Python projects managed by uv, run Python tools with `uv run`.

Report:

- observed failure
- root cause
- evidence
- files changed
- verification performed

#!/usr/bin/env bash
set -euo pipefail

echo "=== STATUS ==="
git status --short

echo
echo "=== RECENT COMMITS ==="
git log --oneline -10

echo
echo "=== DIFF ==="
git diff --stat

echo
echo "=== TESTS ==="
uv run pytest -q --tb=short

python -m pytest -q --tb=short

if rg 'app\.database' frontend/src
then
    echo "Frontend may not import app.database"
    exit 1
fi

"Don't import X here."
→ dependency check

"Every endpoint needs authorization."
→ middleware + test

"Don't forget to regenerate the schema."
→ CI check

"Every bug fix needs a regression test."
→ workflow rule

"Don't modify generated files."
→ generated-file check

uv run ruff check .
uv run mypy .
uv run pytest

python -m ruff check .
python -m mypy .
python -m pytest

6. Зробіть найпростіше рішення правильним

Під час виконання етапу „Зробити найпростішим“ спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність подальших змін у коді. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Робіть контрольні точки після дорогих кроків. Система відновлення не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор перезапускає пізнішу ланку. Під час виконання етапу „Зробити найпростішим“ спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність подальших змін у коді. Віддавайте перевагу малим, тестованим одиницям перед величезними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану систему обробки даних.

components/
services/
hooks/
types/
validation/
screens/

features/
├── billing/
│   ├── api.ts
│   ├── model.ts
│   ├── BillingPage.tsx
│   └── BillingPage.test.tsx
│
└── login/
    ├── api.ts
    ├── model.ts
    ├── LoginPage.tsx
    └── LoginPage.test.tsx

7. Використовуйте нового агента як рецензента

Етап „7. Використовуйте нового агента“ найкраще функціонує, якщо його розглядати як вимірювану характеристику. Збережіть один ідеальний запис, один випадок невдачі та примітку про скасування змін перед розширенням обсягу роботи. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не погоджуйтесь на мовчазне часткове виконання завдань. Зберігайте структуру графа простою та типованою. Вкладені елементи приховують інформацію про те, який вузол заповнив певне поле, що ускладнює продовження роботи після перерв.

Agent A
    ↓
implements
    ↓
Agent B
    ↓
reviews from fresh context

Check:

1. Does the change actually satisfy the task?
2. Can you reproduce the original bug?
3. Are edge cases missing?
4. Were tests weakened?
5. Is there unnecessary complexity?
6. Are architectural boundaries violated?
7. Is existing functionality duplicated?
8. Do the tests verify behavior?

For Python changes, run the relevant checks yourself:

    uv run ruff check .
    uv run mypy .
    uv run pytest

python -m ruff check .
python -m mypy .
python -m pytest

confirmed defect
plausible concern
stylistic preference

8. Паралелізуйте роботу за допомогою робочих дерев, а не хаосу

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

git worktree add ../app-auth -b agent/auth
git worktree add ../app-search -b agent/search
git worktree add ../app-billing -b agent/billing

app-auth/
app-search/
app-billing/

uv sync
uv run pytest

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m pytest

Agent 1: investigate authentication bug
Agent 2: implement CSV export
Agent 3: profile search performance

Agent 1: refactor authentication
Agent 2: refactor authentication differently
Agent 3: rename files both others are editing

9. Розглядайте кожну корекцію людини як дані

Принцип «9 Treat every human stage» функціонує найкраще, коли кожен етап розглядається як вимірювана поверхня. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь граф. Тримайте стан графа простим та типованим. Вкладені блоки приховують інформацію про те, який вузол заповнив яке поле, і ускладнюють відновлення роботи після перерв. Принцип «9 Treat every human stage» функціонує найкраще, коли кожен етап розглядається як вимірювана поверхня. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Віддавайте перевагу малим, тестованим одиницям перед величезними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій.

Agent lacked project knowledge?
→ improve AGENTS.md

Agent didn't know the procedure?
→ create a Skill

Bug escaped?
→ regression test

Same architectural mistake again?
→ CI/static rule

Task was ambiguous?
→ improve task template

Agent trusted its own solution too easily?
→ independent reviewer

agent makes mistake
       ↓
human understands why
       ↓
lesson becomes process
       ↓
process becomes Skill/test/CI
       ↓
future agent avoids whole category of mistake

Настанови щодо створення інфраструктури

Для цього етапу налаштування необхідно спочатку визначити вхідні дані, відповідального за крок та критерії завершення перед зміною коду. Оператори мають мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Призначте назви для результатів роботи, визначте критерії успіху та не допускайте мовчазного часткового завершення. Вимагайте людського схвалення для операцій, які призводять до витрат грошей чи змінюють дані у продакшені. Компіляційне підключення елементів не є гарантією повноти бізнес-процесу.

pyproject.toml
uv.lock
AGENTS.md
Makefile
scripts/verify.sh
skills/debug-with-evidence/SKILL.md
skills/review-change/SKILL.md

uv init

uv sync

uv add --dev pytest ruff mypy

uv run pytest
uv run ruff check .
uv run mypy .

pip install pytest ruff mypy

python -m pytest
python -m ruff check .
python -m mypy .

1. Investigate.
2. Reproduce.
3. Write failing test.
4. Implement smallest fix.
5. Run fast tests.
6. Run full verification.
7. Fresh agent reviews diff.
8. Human corrections become permanent rules.

Own this task end to end.

Before editing:
- inspect the relevant implementation,
- reproduce the problem,
- examine similar existing code.

During implementation:
- make the smallest coherent change,
- add or update tests,
- use `uv run` for Python tools,
- verify while iterating.

Before completion:
- run full verification,
- inspect the final diff,
- independently check the original requirement.

Report what changed, what was verified,
and any remaining uncertainty.

Більша ідея

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

prompt → code

requirement
    ↓
agent
    ↓
code
    ↓
execution
    ↓
verification
    ↓
review
    ↓
feedback
    ↓
better Skills / tests / architecture
    ↺

uv run pytest tests/test_bug.py -q
uv run ruff check .
uv run mypy .
make verify

python -m pytest tests/test_bug.py -q
python -m ruff check .
python -m mypy .
make verify

Чек-лист операцій

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

Документуйте одночасно шлях успішного виконання та шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.

Створюйте контрольні точки після дорогих кроків. Функція відновлення не повинна знову стягувати плату за той самий виклик LLM, коли оператор намагається знову виконати пізніший етап.

Фіксуйте версії залежностей та записуйте хеш-значення зображення, яке використовувалося під час демонстрації. Відтворюваність краща за індивідуальні знання спеціалістів.

Віддавайте перевагу невеликим, тестованим одиницям коду перед складними скриптами. Якщо якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність операцій.

Створюйте контрольні точки після дорогих кроків. Функція відновлення не повинна знову стягувати плату за той самий виклик LLM, коли оператор намагається знову виконати пізніший етап.

Перш ніж запускати стек у продакшн, заморозьте версії, створіть «золотий» запис для критичного шляху та підтвердьте кроки відкату. У спільних середовищах необхідні обмеження на частоту запитів, перевірки прав власності та чіткий власник для зміни секретів. Віддавайте перевагу надійності перед креативними одноразовими демонстраціями.

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