Cheatsheet ng harness ng agent: mga bahagi, file, problema, at checklist sa paglulunsad

Limang subsystem ng harness

Ayos ng pagpapatupad mula sa simula: feedback → tagubilin → estado → kapaligiran → kasangkapan.

Mga file ng harness

Balangkas ng AGENTS.md

# Proyekto: payment backend (FastAPI, PostgreSQL)

## Paglulunsad
docker compose up -d && ./scripts/init.sh

## Verification
make check   # lint, type, unit, arch-check
make e2e     # mga end-to-end na senaryo

## Definition of Done
- make check at make e2e — code 0
- ang feature ay inilipat sa passing ng scripts/verify.sh
- na-update ang PROGRESS.md

## MUST
- ang DB query ay sa pamamagitan lang ng repository
- ang mga secret ay mula lang sa environment variable

## Mga dokumento
- docs/payments.md — kapag gawain ay tungkol sa bayad at refund
- docs/migrations.md — kapag binabago ang schema ng DB

Mga status ng feature

Mga antas ng verification

Karapatang sabihing «tapos na» ay pagkatapos lang ng pinakamataas na antas. Ang berdeng unit test ay hindi katumbas ng pagiging handa.

Paggawang masusunod ang mga panuntunan

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: hindi direktang kumokonekta ang mga service sa DB"
  echo "FIX: gamitin ang repository mula sa app/repositories/"
  fail=1
fi
exit $fail

Mga karaniwang problema at solusyon

Mga tungkulin para sa mahabang gawain

Badyet para sa autonomous na trabaho

• Layunin — isang pangungusap (halimbawa, gawing passing ang lahat ng feature).
• WIP=1, limitasyon sa oras at pagsubok bawat feature.
• Patuloy na tumataas ang sukatan, agad i-rollback ang regression.
• Migration, imprastraktura, pera — i-escalate sa tao.
• Pagkatapos ng ilang nabigong review — simulan ulit ang feature na may malinis na context.

Checklist bago ilunsad ang agent

1. May AGENTS.md: stack, paraan ng paglulunsad, command ng verification, DoD.
2. Pumapasa ang make check sa malinis na clone.
3. Maaaring ulitin ang kapaligiran: lock file, Docker o devcontainer.
4. May access ang agent sa kinakailangang command, at ipinagbabawal o nasa sandbox ang mapanganib na mga command.
5. May E2E kahit para sa pangunahing senaryo.
6. May PROGRESS.md at panuntunang basahin ito sa simula ng session.
7. Naka-status ang mga feature sa listahan, isa lang ang active.
8. Ang status na passing ay itinatakda ng script.
9. May WHY at FIX ang mga mensahe ng pagsusuri.
10. May acceptance criteria at malinaw na saklaw ang gawain.
11. Natukoy kung ano ang nangangailangan ng desisyon ng tao.
12. Nasukat ang verification gap bago ang mga pagbabago, para may pagkukumparahan.

Mga sukatan ng harness

Buod

Ang harness ay saradong loop, hindi isang file: tagubilin, kasangkapan, kapaligiran, estado, at feedback. Magsimula sa verification, panatilihing maikli ang AGENTS.md, ibigay ang status na «tapos» sa script, at regular na suriin ang harness. Lahat ng ito ay pinagsasama sa isang totoong proyekto sa kursong harness engineering.