சீட் ஷீட்

Agent harness சுருக்கக் குறிப்பேடு: கூறுகள், கோப்புகள், பிரச்சினைகள், தொடக்கப் பட்டியல்

புதுப்பிக்கப்பட்டது: 12.10.2026 · Skillaria.Top

Agent harness ஐந்து கூறுகளைக் கொண்டது: வழிகாட்டல், கருவிகள், சூழல், நிலை, பின்னூட்டம். குறைந்தபட்சக் கோப்புத் தொகுப்பு: சுருக்கமான ரௌட்டராக AGENTS.md, சரிபார்ப்பு scripts (make check, verify.sh), முன்னேற்றக் கோப்பு, நிலையுடன் கூடிய அம்சப் பட்டியல்; தயார்நிலை நிலையை முகவர் அல்ல, script தருகிறது.

Agent harness-இன் ஐந்து கூறுகள்

கூறு	என்ன	கருவிகள்	உடைவதன் அறிகுறி
வழிகாட்டல்	திட்டம் பற்றி முகவர் அறிய வேண்டியவை	AGENTS.md / CLAUDE.md, skills, docs/, ADR	அறியப்பட்ட மரபுகளை மீறுகிறான்
கருவிகள்	முகவர் என்ன செய்ய முடியும்	shell, tests, linter, browser, MCP சேவையகங்கள்	«விரும்புகிறான், ஆனால் முடியவில்லை»
சூழல்	முகவர் எங்கே வேலை செய்கிறான்	lock கோப்புகள், Docker/devcontainer, git worktree, sandbox, init.sh	அமர்வு சூழலைச் சரிசெய்வதில் தொடங்குகிறது
நிலை	மறுதொடக்கத்துக்குப் பின்னும் நீடிப்பது	PROGRESS.md, DECISIONS.md, feature_list.json, commit-கள்	புதிய அமர்வுக்கு வேலை எங்கே நின்றது தெரியாது
பின்னூட்டம்	முகவர் தன் பிழைகளை எப்படி அறிகிறான்	make check, E2E, hooks, arch-check, மதிப்பீட்டாளர்	«முடிந்தது», ஆனால் வேலை செய்யவில்லை

முதலிலிருந்து உருவாக்கும் வரிசை: பின்னூட்டம் → வழிகாட்டல் → நிலை → சூழல் → கருவிகள்.

Harness கோப்புகள்

கோப்பு	பணி	விதி
AGENTS.md / CLAUDE.md	நுழைவாயில்: திட்டம் என்ன, எப்படி இயக்குவது, எப்படிச் சரிபார்ப்பது	சுருக்கமான ரௌட்டர் (சுமார் 80 வரிகள்), «எப்போது படிக்க» நிபந்தனையுடன் ஆவண இணைப்புகள்
docs/*.md	தலைப்புவாரி விவரங்கள்	தேவைப்படும்போது படிக்கப்படும், முழுவதும் அல்ல
.claude/skills/*/SKILL.md	மீண்டும் வரும் நடைமுறைகள் (deploy, review)	பணி விவரத்துடன் பொருந்தும்போது ஏற்றப்படும்
PROGRESS.md	நிலை, முடிந்தவை, தடைகள், அடுத்த படிகள்	ஒவ்வோர் அமர்வின் முடிவிலும் புதுப்பிக்கவும்
DECISIONS.md	முடிவு, காரணம், நிராகரித்த விருப்பங்கள்	முடிவை மட்டுமல்ல, பாதையையும் எழுதுங்கள்
feature_list.json	அம்சங்கள்: behavior, verification, state	ஒரே ஓர் அம்சம் மட்டும் active (WIP=1)
scripts/verify.sh	அம்சத்தைச் சரிபார்த்து passing-க்கு மாற்றுதல்	passing-ஐ அமைக்கும் ஒரே நபர், SHA உடன்
scripts/arch-check.sh	கட்டமைப்பு எல்லைகள்	குறியீடு 1 + வெளியீட்டில் WHY மற்றும் FIX
scripts/init.sh	வேலைக்கு முன் சூழல் சரிபார்ப்பு	சூழல், சுத்தமான git, பச்சை make check, செயலில் அம்சம்
sprint contract	குறியீட்டுக்கு முன் ஒவ்வோர் அம்சத்தின் ஒப்பந்தம்	எல்லைக்குள் / எல்லைக்கு வெளியே / திறந்த கேள்விகள்
.claude/settings.json	Claude Code அனுமதிகளும் hooks-உம்	நிகழ்வுகளில் சரிபார்ப்புகள், முகவரின் நினைவில் அல்ல

AGENTS.md அமைப்பு

# திட்டம்: payment backend (FastAPI, PostgreSQL)

## இயக்குதல்
docker compose up -d && ./scripts/init.sh

## சரிபார்ப்பு
make check   # lint, type, unit, arch-check
make e2e     # முடிவிலிருந்து-முடிவு காட்சிகள்

## Definition of Done
- make check மற்றும் make e2e — குறியீடு 0
- scripts/verify.sh மூலம் அம்சம் passing-க்கு மாற்றப்பட்டது
- PROGRESS.md புதுப்பிக்கப்பட்டது

## MUST
- database வினவல்கள் repository வழியாக மட்டும்
- ரகசியங்கள் சூழல் மாறிகளிலிருந்து மட்டும்

## ஆவணங்கள்
- docs/payments.md — பணி கட்டணம் மற்றும் திருப்பிச் செலுத்தலைத் தொட்டால்
- docs/migrations.md — database schema மாறினால்

அம்சத்தின் நிலைகள்

நிலை	பொருள்	யார் மாற்றுவார்
pending	வரிசையில் உள்ளது	திட்டமிடுபவர்
active	வேலை நடக்கிறது (ஒன்று மட்டும்)	முகவர், தொடக்கத்தில்
passing	சரிபார்ப்பு தேறியது	verify.sh மட்டும்
blocked	மனித முடிவு தேவை	முகவர், காரணத்துடன்

சரிபார்ப்பு நிலைகள்

நிலை	என்ன	எப்போது
1	Lint, type	எப்போதும்
2	Unit மற்றும் integration tests	எப்போதும்
3	E2E	ஒன்றுக்கு மேற்பட்ட அடுக்குகளைத் தொட்டால்; «முடிந்தது» என்பதற்கு முன்
4	arch-check	புதிய அடுக்குக் கடந்த இறக்குமதிகள்

«முடிந்தது» என்று சொல்லும் உரிமை மேல் நிலைக்குப் பின்னரே. பச்சையான unit tests தயார்நிலை அல்ல.

விதிகளை இயந்திரமயமாக்குதல்

நிலை	கருவி	செலவு
Guard grep	WHY/FIX செய்தியுடன் வடிவத்தைத் தேடும் script	நிமிடங்கள்
Linter விதி	import-linter (Python), dependency-cruiser, eslint-plugin-boundaries (JS/TS)	ஒரு மணி நேரம்
Architecture test	அடுக்கு மீறப்பட்டால் தோல்வியடையும் CI test	அதிகம், ஆனால் make check-இல் தெரியும்

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: service நேரடியாக database-ஐத் தொடக்கூடாது"
  echo "FIX: app/repositories/ இலிருந்து repository-ஐப் பயன்படுத்துங்கள்"
  fail=1
fi
exit $fail

பொதுவான பிரச்சினைகளும் தீர்வுகளும்

பிரச்சினை	கூறு	தீர்வு
CLAUDE.md-இல் உள்ள விதி பின்பற்றப்படவில்லை	வழிகாட்டல்	கோப்பைச் சுருக்குங்கள், விதியைச் சரிபார்ப்பாக அல்லது hook ஆக மாற்றுங்கள்
முகவரால் tests-ஐ இயக்க முடியவில்லை	கருவிகள்	கட்டளைக்கு அனுமதி கொடுங்கள், image-இல் சார்புகளை நிறுவுங்கள்
ஒவ்வொரு இயந்திரத்திலும் நடத்தை வேறுபடுகிறது	சூழல்	lock கோப்புகள், Docker/devcontainer, நிலையான runtime பதிப்புகள்
அமர்வுகளுக்கு இடையே மறதி	நிலை	PROGRESS.md, அமர்வு ஒப்படைப்பு, தொடக்கத்தில் படித்தல்
மூன்று அம்சங்கள் தொடங்கின, ஒன்றும் முடியவில்லை	நிலை	feature_list.json-இல் WIP=1
«முடிந்தது», ஆனால் வேலை செய்யவில்லை	பின்னூட்டம்	DoD, E2E, verify.sh, சுயாதீன மதிப்பீட்டாளர்
Tests பச்சை, அம்சம் உடைந்தது	பின்னூட்டம்	உண்மையான database மற்றும் அமைப்புகளுடன் E2E
முகவர் மோசமான வடிவங்களை நகலெடுக்கிறான்	பின்னூட்டம்	முதல் நாளிலிருந்தே arch-check
முகவர் என்ன செய்தான் என்று புரியவில்லை	நிலை	சிறிய commit-கள், PROGRESS.md அறிக்கை, DECISIONS.md
முகவர் இரவில் சூழலைச் சிதைத்தான்	சூழல்	Sandbox, git worktree, சோதனைச் சாவடிகள், init.sh மூலம் rollback
அதே review கருத்து இரண்டு முறை	Harness முழுவதும்	make check-இல் சரிபார்ப்பாக மாற்றுங்கள், வழிகாட்டலிலிருந்து உரையை நீக்குங்கள்

நீண்ட வேலைகளுக்கான பாத்திரங்கள்

பாத்திரம்	செய்வது	செய்யாதது
திட்டமிடுபவர்	ஏற்பு அளவுகோல்களுடன் அம்சங்கள்	குறியீடு எழுதுவதில்லை
உருவாக்குபவர்	ஓர் அம்சத்தைச் செயல்படுத்தி tests-ஐ இயக்குகிறார்	தயாரா என்று முடிவு செய்வதில்லை
மதிப்பீட்டாளர்	rubric அடிப்படையில் கோப்பு, வரி, பதிவுடன் தீர்ப்பு	உருவாக்குபவரின் வாதங்களைப் பார்ப்பதில்லை
Merge	review == pass ஆனால் commit	இது குறியீடு, முகவர் அல்ல

தானியங்கி வேலையின் பட்ஜெட்

இலக்கு — ஒரு வாக்கியம் (உதாரணமாக எல்லா அம்சங்களையும் passing ஆக்குவது).
WIP=1, ஓர் அம்சத்துக்கு நேரம் மற்றும் முயற்சிகளின் வரம்பு.
அளவீடு தொடர்ந்து உயர்கிறது; regression என்றால் உடனடி rollback.
Migrations, உள்கட்டமைப்பு, பணம் — மனிதரிடம் அதிகரிப்பு.
பல review தோல்விகளுக்குப் பின் அம்சம் சுத்தமான சூழலுடன் மீண்டும் தொடங்கும்.

முகவரைத் தொடங்குவதற்கான பட்டியல்

AGENTS.md உள்ளது: stack, இயக்கும் முறை, சரிபார்ப்புக் கட்டளை, DoD.
சுத்தமான clone-இல் make check தேறுகிறது.
சூழல் மீண்டும் உருவாக்கக்கூடியது: lock கோப்புகள், Docker அல்லது devcontainer.
தேவையான கட்டளைகள் முகவருக்குக் கிடைக்கின்றன; ஆபத்தானவை தடுக்கப்பட்டுள்ளன அல்லது sandbox-இல் உள்ளன.
முக்கியக் காட்சிக்காவது ஒரு E2E உள்ளது.
PROGRESS.md உள்ளது, அமர்வின் தொடக்கத்தில் அதைப் படிக்க விதி உள்ளது.
அம்சங்கள் நிலையுடன் பட்டியலில் உள்ளன, ஒன்று மட்டும் செயலில்.
Passing நிலையை script அமைக்கிறது.
சரிபார்ப்புச் செய்திகளில் WHY மற்றும் FIX உள்ளன.
பணி ஏற்பு அளவுகோல்களுடனும் எல்லை வரம்புகளுடனும் எழுதப்பட்டுள்ளது.
எதற்கு மனித முடிவு தேவை என்று வரையறுக்கப்பட்டுள்ளது.
மாற்றங்களுக்கு முன் verification gap ஒப்பீட்டுக்காக அளக்கப்பட்டுள்ளது.

Harness அளவீடுகள்

அளவீடு	எப்படிக் கணக்கிடுவது
Verification gap	10 பணிகளில் «முடிந்தது» என்றும் சரிபார்ப்பு உறுதிப்படுத்தாதவற்றின் விகிதம்
MTTR	உடைவிலிருந்து வேலை நிலைக்குத் திரும்பும் வரையிலான நேரம்
Cold start	புதிய அமர்வு «எங்கே இருக்கிறோம், அடுத்து என்ன» என்பதற்கு ஊகிக்காமல் பதிலளிக்கிறதா
Ablation	நிலையான பணித்தொகுப்பில் ஒரு கூறை அணைக்கும்போது ஏற்படும் வீழ்ச்சி

சுருக்கம்

Harness ஒரு சுழற்சி, ஒரு கோப்பு அல்ல: வழிகாட்டல், கருவிகள், சூழல், நிலை, பின்னூட்டம். சரிபார்ப்பில் தொடங்குங்கள், AGENTS.md-ஐ சுருக்கமாக வையுங்கள், தயார்நிலை நிலையை script-க்குக் கொடுங்கள், harness-ஐ அவ்வப்போது மறுஆய்வு செய்யுங்கள். இவை அனைத்தும் பாடநெறியின் ஒரு திட்டத்தில் ஒரு முழு அமைப்பாக இணைகின்றன.

அடிக்கடி கேட்கப்படும் கேள்விகள்

AGENTS.md மற்றும் CLAUDE.md இடையே என்ன வேறுபாடு?

நோக்கத்தில் ஒன்றே: முகவருக்கான வழிகாட்டல் கோப்பு. CLAUDE.md-ஐ Claude Code படிக்கிறது, AGENTS.md பல முகவர்களுக்கான பொதுவான வடிவம்; CLAUDE.md-இல் AGENTS.md-ஐக் குறிப்பிட்டால் போதும்.

AGENTS.md-இல் எத்தனை வரிகள் இருக்க வேண்டும்?

கடுமையான வரம்பு இல்லை, ஆனால் நுழைவுக் கோப்பு சுருக்கமாக இருப்பது நல்லது — சுமார் நூறு வரிகள், அட்டவணை போல. விவரங்கள் தனி ஆவணங்களுக்குச் செல்லும்.

சிறிய திட்டத்துக்கு feature_list.json தேவையா?

ஒரு முறை சிறிய மாற்றங்களுக்குத் தேவையில்லை. முகவர் பல அம்சங்களை வரிசையாக அல்லது பல அமர்வுகளில் செய்யும்போது அது பலன் தரும்.

முகவருக்குத் தேவையான ரகசியங்களை எங்கே வைப்பது?

சூழல் மாறிகளில் அல்லது ரகசிய மேலாளரில், வழிகாட்டல் கோப்பிலோ குறியீட்டிலோ அல்ல. முகவருக்குச் சூழலுக்கான அணுகலைக் கொடுங்கள், உரையில் எழுதப்பட்ட மதிப்புகளுக்கு அல்ல.

இந்தத் தலைப்பை வீடியோவில் கற்றுக்கொள்ளுங்கள்

“Harness Engineering: инженерия надёжности AI-агентов” பாடநெறியில் இந்தத் தலைப்பு பயிற்சியுடன் விரிவாக விளக்கப்பட்டுள்ளது.

பாடநெறிக்குச் செல்