Karatasi ya kudanganya ya harness ya wakala: vipengele, faili, matatizo na orodha ya kuanzisha

Vipengele vitano vya harness ya wakala

Mpangilio wa kujenga kutoka mwanzo: maoni → maelekezo → hali → mazingira → zana.

Faili za harness

Muundo wa AGENTS.md

# Mradi: backend ya malipo (FastAPI, PostgreSQL)

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

## Ukaguzi
make check   # lint, aina, kitengo, arch-check
make e2e     # hali za mwisho-hadi-mwisho

## Definition of Done
- make check na make e2e — msimbo 0
- kipengele kinapandishwa hadi passing na skripti ya scripts/verify.sh
- PROGRESS.md imesasishwa

## MUST
- maswali ya database kupitia repository tu
- siri kutoka kwenye vigezo vya mazingira tu

## Nyaraka
- docs/payments.md — kazi inapogusa malipo na marejesho
- docs/migrations.md — schema ya database inapobadilika

Hali za kipengele

Ngazi za uthibitishaji

Haki ya kusema «imekamilika» ni baada ya ngazi ya juu kabisa tu. Majaribio ya kitengo ya kijani si utayari.

Kufanya kanuni ziwe za kimashine

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: service haziungani moja kwa moja na database"
  echo "FIX: tumia repository kutoka app/repositories/"
  fail=1
fi
exit $fail

Matatizo ya kawaida na suluhisho

Majukumu kwa kazi ndefu

Bajeti ya kazi ya kujiendesha

• Lengo — sentensi moja (kwa mfano kupeleka vipengele vyote hadi passing).
• WIP=1, kikomo cha muda na majaribio kwa kila kipengele.
• Kipimo kinapanda kwa mfululizo; regression inamaanisha rollback mara moja.
• Migration, miundombinu, fedha — upandishaji kwa binadamu.
• Baada ya review kadhaa kushindwa, kipengele kinaanzishwa upya kwa muktadha safi.

Orodha ya kuanzisha wakala

1. AGENTS.md ipo: stack, jinsi ya kuendesha, amri ya ukaguzi, DoD.
2. make check inapita kwenye clone safi.
3. Mazingira yanaweza kuzalishwa upya: faili za lock, Docker au devcontainer.
4. Amri zinazohitajika zinapatikana kwa wakala; zile hatari zimezuiwa au ziko kwenye sandbox.
5. Kuna E2E angalau kwa hali kuu.
6. Kuna PROGRESS.md na kanuni ya kuisoma mwanzoni mwa kikao.
7. Vipengele vipo kwenye orodha pamoja na hali zake, kimoja tu kikiwa kinatumika.
8. Hali ya passing inatolewa na skripti.
9. Ujumbe wa ukaguzi una WHY na FIX.
10. Kazi imeandikwa pamoja na vigezo vya kukubalika na mipaka ya wigo.
11. Imeamuliwa ni nini kinahitaji uamuzi wa binadamu.
12. Verification gap imepimwa kabla ya mabadiliko, kwa ulinganisho.

Vipimo vya harness

Kwa ufupi

Harness ni mzunguko, si faili moja: maelekezo, zana, mazingira, hali na maoni. Anza na ukaguzi, weka AGENTS.md fupi, mpe skripti jukumu la hali ya kukamilika, na pitia harness mara kwa mara. Yote haya yanakusanywa kuwa kitu kimoja katika mradi wa kozi ya harness engineering.