AI முகவர்களின் கண்காணிப்புத்திறன் (observability): முகவர் என்ன செய்தது என்று எப்படிப் புரிந்துகொள்வது, அதற்கு என்ன பதிவு செய்ய வேண்டும்

AI முகவர் observability என்றால் என்ன

AI முகவர் observability என்பது நினைவையும் முகவரின் சொற்களையும் அல்ல, தடயங்களை வைத்து மூன்று கேள்விகளுக்கு பதில் சொல்லும் திறன்: அது என்ன செய்தது, ஏன் அப்படிச் செய்தது, முடிவு சரி என்று எதனால் உறுதியாகிறது. இருபது நிமிட வேலைக்குப் பின் முகவர் «முடிந்தது, ஆனால் இரண்டு சோதனைகள் தோல்வியடைகின்றன, ஒருவேளை நேரப் பிரச்சினையால்» என்று சொல்கிறது, «எந்தப் பாதைகள் பாதிக்கப்பட்டன» என்ற கேள்விக்கு «குறியீட்டைப் பார்க்க விடுங்கள்» என்று பதில் சொல்கிறது என்றால் — observability இல்லை. முகவர் முட்டாள் அல்ல: அதனிடம் காட்ட எதுவும் இல்லை.

பிரச்சினை அமைப்புரீதியானது. அதே முகவர் ஒரு வாரத்தில் பத்து முறை நேர்மையாக «முடிந்தது» என்று சொல்லலாம், ஒவ்வொரு முறையும் அதற்கு வேறு அர்த்தம் இருக்கும்: ஓரிடத்தில் எல்லா சோதனைகளும் ஓடின, ஓரிடத்தில் ஒன்று மட்டும், ஓரிடத்தில் எதுவுமே இல்லை. திட்டம் பழையதாகும்போது ஒவ்வொரு அடுத்த அமர்வும் அகழ்வாராய்ச்சியிலிருந்து தொடங்குவதால் அதன் விலை அதிகரிக்கிறது.

இரண்டு அடுக்குகள்: இயக்க நேரமும் செயல்முறையும்

Observability பதிவுகளுடன் குழப்பிக்கொள்ளப்படுகிறது, ஆனால் பதிவுகள் பாதி மட்டுமே.

இயக்க நேரம் மட்டும் இருந்தால்: எது தோல்வியடைந்தது என்று தெரியும், ஆனால் எதை அடைய முயன்றோம் என்று தெரியாது. செயல்முறை மட்டும் இருந்தால்: எதை விரும்பினோம் என்று தெரியும், ஆனால் ஏன் தோல்வியடைந்தது என்று தெரியாது. இரண்டும் தேவை.

முகவர் இதை தானாகச் செய்ய முடியாது ஏன்

முகவரிடம் «நன்றாகப் பதிவு செய்» என்று சொல்வது மூன்று காரணங்களால் வேலை செய்யாது.

• எது தெரியாது என்று அதற்குத் தெரியாது. எதன் முக்கியத்துவம் பற்றி அதற்கு யூகம் இல்லையோ, அந்த சமிக்ஞையை முகவர் பதிவு செய்யாது.
• வடிவம் மாறுகிறது. ஒரு அமர்வில் விரிவாக எழுதுகிறது, இன்னொன்றில் ஒரு வரியில். அமர்வுகளை ஒப்பிடுவதும் மொத்தக் கணக்கு எடுப்பதும் சாத்தியமில்லை.
• செயல்முறையை பதிவுகளால் மூட முடியாது. «ஏன் இப்படி» என்ற கேள்விக்கான பதில் வேலைக்கு முன் உருவாக்கப்பட்ட ஆவணங்களில் உள்ளது, கட்டளை வெளியீட்டில் அல்ல.

எனவே observability harness-இல் — முகவரின் சூழலில் — வைக்கப்படுகிறது: வார்ப்புருக்கள், hooks, ஸ்கிரிப்டுகள், கட்டாய அறிக்கை வடிவம்.

எதைப் பதிவு செய்ய வேண்டும்: குறைந்தபட்சத் தொகுப்பு

நல்ல பதிவு ஒன்றுக்கொன்று கிடைக்கும் அனைத்தின் நகல் அல்ல, வேலையின் போக்கை மீட்டெடுக்கவும் புள்ளிவிவரம் எடுக்கவும் உதவும் உண்மைகளின் தொகுப்பு.

• அடையாளங்காட்டிகள்: அமர்வின் id, பணி அல்லது அம்சத்தின் id, முகவரின் மாதிரி.
• பக்கவிளைவுகள் உள்ள செயல்கள்: என்ன கட்டளைகள் இயக்கப்பட்டன, எந்தக் கோப்புகள் மாற்றப்பட்டன. கோப்புகளைப் படிப்பது பொதுவாக பதிவு செய்யத் தேவையில்லை.
• சரிபார்ப்பு முடிவுகள்: எந்தச் சரிபார்ப்புக் கட்டளை, திரும்பிய code, எத்தனை சோதனைகள் தேறின, எத்தனை தோல்வியடைந்தன.
• மறுமுயற்சிகள்: ஒரு படிக்கு எத்தனை முயற்சிகள் ஆயின, அவை எதில் வேறுபட்டன.
• செலவு: கருவி கொடுத்தால் டோக்கன்களும் நேரமும்.
• முடிவு: பணி ஏற்கப்பட்டதா, நிராகரிக்கப்பட்டதா அல்லது கைவிடப்பட்டதா, ஏன்.

எதை எழுதக்கூடாது: ரகசியங்கள், அணுக்க டோக்கன்கள், கட்டளை வெளியீட்டிலிருந்து தனிப்பட்ட தரவு. பதிவு பொது அணுகலுக்கோ மீண்டும் மாதிரியின் context-க்கோ செல்லலாம்.

Claude Code hooks மூலம் செயல் பதிவு

Claude Code-இல் பதிவை hooks மூலம் வைத்திருப்பது வசதியானது — அவை கருவியே இயக்கும் கட்டளைகள், மாதிரி அல்ல, எனவே அவை எப்போதும் இயங்குகின்றன. Hook நிகழ்வின் விவரங்கள் கொண்ட JSON-ஐ உள்ளீடாகப் பெறுகிறது: அமர்வின் id, கருவியின் பெயர், அதன் அளவுருக்கள். Bash, Edit அல்லது Write அழைக்கப்பட்ட ஒவ்வொரு முறையும் பதிவில் ஒரு வரி சேர்க்கும் .claude/settings.json அமைப்பு:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — ஒவ்வொரு செயலுக்கும் ஒரு JSON வரி
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

JSONL வடிவம் (ஒரு வரியில் ஒரு JSON பதிவு) jq மூலம் வடிகட்ட எளிதானது, எந்த பகுப்பாய்வு அமைப்பிலும் ஏற்றலாம். கூடுதலாக, Claude Code முழு அமர்வு வரலாற்றையும் ~/.claude/projects/ அடைவில் உள்ளூரில் சேமிக்கிறது — முழு பகுத்தறிவையும் வெளியீட்டையும் பார்க்க வேண்டுமானால் அதைத் திறக்கலாம், ஆனால் புள்ளிவிவரத்துக்கு உங்கள் சுருக்கமான பதிவு வசதியானது.

Trace: அமர்வுக்கு ஒரு trace, பணிக்கு ஒரு span

முகவர்கள் பலவாக இருக்கும்போது அல்லது அட்டவணைப்படி ஓடும்போது உரைப் பதிவுகள் போதாது: மொத்தக் கணக்குகள் தேவை. இங்கே வழக்கமான பகிர்ந்த trace கருவிகளும் OpenTelemetry தரநிலையும் பயன்படுகின்றன.

• Trace — ஒரு முகவர் அமர்வு.
• Span — அமர்வுக்குள் ஒரு பணி.
• உள் span-கள் — சரிபார்ப்புப் படிகள்: build, சோதனைகள், e2e.

ஒவ்வொரு span-க்கும் குறைந்தபட்ச பண்புகள்: அம்சம் மற்றும் அமர்வின் id, மாதிரி, சரிபார்ப்பின் முடிவு, டோக்கன்கள், மறுமுயற்சிகளின் எண்ணிக்கை. இத்தகைய தரவை Jaeger, Grafana Tempo, Honeycomb-இல் படிக்கலாம், ஒரே அமர்வில் தெரியாத கேள்விகளுக்கு பதில் சொல்கின்றன: எந்த வகைப் பணிகளுக்கு அதிக மறுமுயற்சிகள் தேவை, முகவர் எங்கே அதிக டோக்கன்களைச் செலவிடுகிறது, harness-இன் எந்த மாற்றத்துக்குப் பிறகு ஏற்கப்பட்ட பணிகளின் விகிதம் குறைந்தது. Claude Code-க்கு OpenTelemetry மூலம் அளவீடுகளையும் நிகழ்வுகளையும் ஏற்றுமதி செய்யும் வசதி உள்ளது — அது சூழல் மாறிகள் மூலம் இயக்கப்படுகிறது, விவரங்களுக்கு கருவியின் ஆவணம்.

Commit-கள் ஒரு பதிவாக

மலிவான, நம்பகமான பதிவு உங்களிடம் ஏற்கனவே இருக்கிறது — git. அதை வாசிக்கக்கூடியதாக்க வேண்டும் அவ்வளவுதான்.

1. ஒரு commit — ஒரு பணி. அப்போது git log செய்யப்பட்ட வேலைப் பட்டியலுடன் பொருந்தும், ஒரு பணியைத் திரும்பப்பெற ஒரு git revert போதும்.
2. செய்தியில் — என்ன மாற்றப்பட்டது, எப்படி சரிபார்க்கப்பட்டது. «fix» அல்ல, «என்ன மாற்றப்பட்டது, ஏன், எந்தக் கட்டளையால் சரிபார்க்கப்பட்டது».
3. பச்சை சரிபார்ப்புக்குப் பின் மட்டும் commit. அப்போது வரலாற்றின் ஒவ்வொரு புள்ளியும் வேலை செய்யும் நிலை, git bisect குற்றவாளியைக் கண்டுபிடிக்கும்.

fix(payments): தள்ளுபடியை காசுகளுக்கு வட்டமிடுதல்

தள்ளுபடி float-இல் கணக்கிடப்பட்டது, 999.99 தொகையில் ஒரு காசு இழக்கப்பட்டது.
கணக்கீடு int-இல், காசுகளில் மாற்றப்பட்டது.
சரிபார்க்கப்பட்டது: make test (142 passed), make e2e checkout — சரி.
Scope-க்கு வெளியே: அறிக்கைகளில் வட்டமிடல், BACKLOG.md-இல் பதிவு.

முகவரின் அறிக்கை: உணர்வுகளுக்குப் பதிலாக ஆதாரங்கள்

முகவரின் இறுதிச் செய்தியும் observability-இன் ஒரு ஆதாரம், அதற்கு நிலையான வடிவம் இருந்தால். வார்ப்புருவை AGENTS.md அல்லது CLAUDE.md-இல் எழுதுங்கள்:

## பணியின் முடிவில் அறிக்கை
- என்ன செய்யப்பட்டது: மாற்றங்களின் பட்டியல் (கோப்பு — சாராம்சம்)
- எப்படி சரிபார்க்கப்பட்டது: துல்லியமான கட்டளைகளும் அவற்றின் முடிவுகளும்
- எது சரிபார்க்கப்படவில்லை, ஏன்
- பணி ஒப்பந்தத்திலிருந்து விலகல்கள்
- மனிதனுக்கான திறந்த கேள்விகள்

முக்கிய விதி: ஒவ்வொரு கூற்றும் ஆதாரத்தைக் குறிக்கிறது — கோப்பு மற்றும் வரி, சோதனையின் வெளியீடு, பதிவில் ஒரு உள்ளீடு. «நன்றாகத் தெரிகிறது» மற்றும் «எனக்கு சரியாகத் தோன்றுகிறது» அறிக்கையாகக் கருதப்படாது. «எது சரிபார்க்கப்படவில்லை» என்ற பகுதி குறிப்பாக மதிப்புமிக்கது: அது நம்பிக்கையின் எல்லைகளை நேர்மையாகக் காட்டுகிறது.

வேலைக்கு முன் ஒப்பந்தம், பின்னர் rubric

செயல்முறை அடுக்கு வேலைக்கு முன்பே தொடங்குகிறது. குறுகிய பணி ஒப்பந்தம் (sprint contract) scope, ஏற்பு அளவுகோல்கள், «scope-க்கு வெளியே» பகுதி, மனிதன் தீர்க்கும் திறந்த கேள்விகள் ஆகியவற்றைப் பதிவு செய்கிறது. «scope-க்கு வெளியே» பகுதி முடிவைப் பற்றிய சர்ச்சைகளில் பாதியைத் தடுக்கிறது.

வேலைக்குப் பின் முடிவு உணர்வால் அல்ல, rubric-ஆல் மதிப்பிடப்படுகிறது. இல்லையென்றால் இரண்டு அனுபவம் வாய்ந்த மதிப்பாய்வாளர்கள் வெவ்வேறு தீர்ப்புகள் கொடுப்பார்கள், மதிப்பீடு லாட்டரியாகிவிடும்.

ஒவ்வொரு அளவும் A/B/C/D என மதிப்பிடப்படுகிறது, ஆதாரம் இல்லாத மதிப்பீடு செல்லாது. எளிய முடிவு விதி: ஒரு D அல்லது இரண்டு C — என்ன சரி செய்ய வேண்டும் என்ற பட்டியலுடன் நிராகரிக்கவும். அதே rubric-ஐ தனி சரிபார்ப்பு முகவரும் பயன்படுத்தலாம்.

ஒரு அமர்வில் முகவர் என்ன செய்தது என்று பிரித்துப் பார்ப்பது எப்படி

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

1. அடைவின் நிலை: git status — commit ஆகாதது என்ன, குப்பைக் கோப்புகள் உள்ளனவா.
2. வரலாறு: அமர்வின் தொடக்கத்திலிருந்து git log --stat — எந்த commit-கள், எந்தக் கோப்புகள்.
3. மாற்றங்களின் அளவு: git diff --stat main...HEAD, பின்னர் முக்கியக் கோப்புகளின் முழு diff.
4. செயல் பதிவு: எந்தக் கட்டளைகள் இயக்கப்பட்டன, சரிபார்ப்புகள் என்ன திருப்பின.
5. மீண்டும் சரிபார்ப்பு: build-ஐயும் சோதனைகளையும் நீங்களே இயக்குங்கள். கட்டளையின் வெளியீட்டை நம்புங்கள், அதன் சுருக்கத்தை அல்ல.

# கடைசி அமர்வில் முகவர் எந்தக் கட்டளைகளை இயக்கியது
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# எந்தக் கோப்புகள் அடிக்கடி திருத்தப்பட்டன
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

அடிக்கடி நிகழும் தவறுகள்

• அனைத்தையும் பதிவு செய்தல். ஜிகாபைட் கணக்கான நகல்களை யாரும் படிப்பதில்லை. பக்கவிளைவுகள் உள்ள செயல்களையும் சரிபார்ப்பு முடிவுகளையும் எழுதுங்கள்.
• தளர்வான வடிவம். பதிவின் வடிவத்தை முகவரே தீர்மானித்தால் புள்ளிவிவரம் கிடைக்காது. வடிவத்தை harness தீர்மானிக்க வேண்டும்.
• கட்டளை வெளியீடு இல்லாமல் அறிக்கையை நம்புதல். வெளியீடு இல்லாத «சோதனைகள் பச்சை» ஒரு கருத்து மட்டுமே.
• குருட்டு மறுமுயற்சிகள். தோல்விக்கான காரணம் இல்லாமல் முகவர் தற்செயலான இடங்களைத் திருத்துகிறது. முதலில் பதிவின் இணைப்புடன் நோயறிதல், பின்னர் திருத்தம் கேளுங்கள்.
• «பிறகு சுத்தம் செய்வோம்». தற்காலிக கோப்புகளும் commit ஆகாத மாற்றங்களும் அடுத்த அமர்வைக் குழப்புகின்றன: தற்காலிகமானதையும் வேண்டுமென்றே செய்ததையும் அது பிரித்தறியாது.

முடிவு

AI முகவர்களின் observability இரண்டு அடுக்குகளால் கட்டப்படுகிறது: இயக்க நேரம் (hooks வழியாக செயல் பதிவு, trace-கள், பச்சை சரிபார்ப்புடன் commit-கள்) மற்றும் செயல்முறை (குறியீட்டுக்கு முன் பணி ஒப்பந்தம், rubric, ஆதாரங்களுடன் அறிக்கை). அப்போது «முடிந்தது» ஒவ்வொரு அமர்விலும் ஒரே பொருளைத் தரும், முகவரின் வேலையைப் பிரித்துப் பார்ப்பது நிமிடங்களில் முடியும். இந்தத் தலைப்பு ஒரு முழு பின்தள திட்டத்தில் harness engineering பாடநெறியில் நடைமுறையில் விளக்கப்படுகிறது.