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

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

Проблема: верагатна, вы яшчэ выканаеце толькі палову роботы

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

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 bugs demand неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крэтырыя завершэння пры зміне коду. Аперацыйныя працавнікі павінны магчымае перазапускаць крок з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан. Конфігурацыю трэба залічыць праза код аплікацыі. Файлы сераўіса, хранільнікі секрэтных дадзеных і флагі функцыйяў павінны знаходзіцца ў адном месцы, якое працавнікі можуць пераглядаць, не чытаючы весь ланцуг задач. Прызначайце людскія апраўды для рэлейнаў, якіе витрачаюць грошы або зменяюць даны у працэйнай сістэме. Падключэння праз час компіляцыі не ўзначае повнасці бізнес-процэсу. Для стадіі 2 For bugs demand неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крэтырыя завершэння пры зміне коду. Аперацыйныя працавнікі павінны магчымае перазапускаць крок з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан. Валічыце маленькія, тэставальныя елементы пра велікія скрыпты. Калі крок не выйшоў, прычына нехарактернага рэзультата павінна вказываць на адную адпаведальнасць, а не на заплутаны ланцуг задач.

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 «Павтараючыя урокі», спачатку запісайце угоду: неабяжлівыя даны, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список перакладзець пазнейшыя змены коду ў правільны роўнь. Запісвайце часы выканання і кост токенаў або запита праза функцыональныя рэзултаты. Відразлівасць костаў з самага пачатку запобегае неспакойным рахункам, калі працэс пераходзіць з дэмаверсіі ў спяльныя среды. Зробіце перапаконтаванне пасля дорогіх крокаў. Система не должна зноў нараховваць косты за той самы вызыв 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 «Паралелізацыя з worktrees» працюе найэфектывней, калі яго розглядаць як вимерную плошчу. Зафіксавце адна ідеальная версія, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштабы. Запісвайце час выканання і вартасць токеноў або запытаў разам з функцыйнальнымі рэзультатамі. Візуабельнасць вартасцей з самага пачатку запобегае неспакою, калі процес пераходзіць з дэмаверсіі ў спяльныя сераўы. Храніце стан графа ў простам і типаваным формате. Вкладзеныя блокі маскуюць інфармацыю пра тое, який вузел запісаў які поле, і спакшваюць продажчэй работу пасля перерываў.

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 прыемаў для кожнага людзкага этапу» найэфектывейша ўмова — адносіцца да яго як да вимерлівай структуры. Зберагачыце адны ідеальны прыклад, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштаб. Храніце настройкі парадульна ад коду прыемплэю. Файлы сяродавішча, базы секрэтных даных і флагі функций должны знаходзіцца ў аднам месцы, куды аператары можаць адбавляць контроль без неабяжнага чытання всіх дадзеных. Храніце стан структуры у простам і типаваным формате. Вярнутыя структуры маскуюць інфармацію пра тое, канферыткі який вузел запісаў канкрэтны поле, і спакоююць працу пасля перарываў. Пры практыкаванні «9 прыемаў для кожнага людзкага этапу» найэфектывейша ўмова — адносіцца да яго як да вимерлівай структуры. Зберагачыце адны ідеальны прыклад, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштаб. Валіце маленькія, тэставаныя елементы працы над вялікімі скрыптамі. Калі якісь крок не выйшае, прычына неудачы должна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцоўкі задач.

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: не кладзіце ключы прадастаўцаў у репазітарый, задаце верхнюю межу токенаў на сесію і зберагачыце транскрыпты празаўседы ў фікстурах eval, каб пазнейшыя замены модэляў заставаліся пораўнанымі.