चलो एक ऐसी बात पर ईमानदार होते हैं जो हम में से ज्यादातर लोग ज़ोर से नहीं कहते: हम AI-generated कोड की बमुश्किल review करते हैं।

Diff 600 लाइनों का है। Agent ने 14 फाइलें छुई हैं। तुम pull request खोलते हो, changes को scroll करते हो, कुछ functions पर नज़र मारते हो, और merge कर देते हो। शायद पहले tests चलाते हो। शायद नहीं। कोड ठीक दिखता है। Agent ने कहा कि काम हो गया। Ship कर दो।

यह आलस नहीं है। यह एक structural समस्या है। Traditional code review एक ऐसी दुनिया के लिए बनाया गया था जहां इंसान ने कोड लिखा था और पूछने पर अपना reasoning समझा सकता था। जहां diffs 50-200 लाइनों के होते थे क्योंकि एक focused session में इतना ही लिखा जाता है। जहां PR description कहता था "मैंने approach X चुना क्योंकि Y" और तुम उस context पर भरोसा कर सकते थे।

AI agents इस तरह काम नहीं करते। Claude Code दो मिनट में 500 लाइनें working code produce कर सकता है। PR description अक्सर बस "implement feature X" होती है। Diff तुम्हें बताता है क्या बदला लेकिन क्यों के बारे में कुछ नहीं। कोई record नहीं कि agent ने कौन से alternatives consider किए। कोई explanation नहीं कि उसने कौन से tradeoffs किए। कोई proof नहीं कि उसने actually कुछ test किया। तुम एक black box का output review कर रहे हो, और review tool तुम्हें सिर्फ output दिखाता है।

यह article बताता है कि diff-based review agent output के लिए क्यों fail होता है, actually missing layer क्या है, और एक concrete pattern जो AI-generated code को reviewable बनाता है बिना तुम्हारे review time को तिगुना किए।

Review का अंतर

Developers इसके बारे में private में ईमानदार हैं। Community threads में pattern दोहराता है: "मैं ज्यादातर agent diffs को बस skim करता हूं।" "मैं check करता हूं कि tests pass हों और merge कर देता हूं।" "अगर roughly ठीक लगता है, तो approve कर देता हूं।"

यह constraints को देखते हुए rational behavior है। जब कोई human colleague PR submit करता है, तुम्हारे पास context होता है: तुम जानते हो वो किस पर काम कर रहा था, तुमने ticket देखा है, शायद standup में approach पर बात हुई। Diff supplementary है। असली review shared context से हुई।

Agent के साथ, तुम्हारे पास इसमें से कुछ नहीं है। Agent ने task claim किया, तीन मिनट चुप रहा, और एक diff produce किया। एकमात्र context वो one-line description है जो agent ने PR पर छोड़ा। उस diff को scratch से review करना, intent या reasoning के बारे में बिना context के, उसी size के human PR को review करने से 5-10x ज्यादा समय लेता है। तो लोग करते नहीं। वो कुछ critical areas spot-check करते हैं और approve कर देते हैं।

नतीजा predictable है। ऐसे bugs निकल जाते हैं जो context के साथ पकड़ लिए जाते। Architectural drift accumulate होता है जब agents छोटे decisions लेते हैं जो compound होते हैं। Code quality subtly degrade होती है: broken नहीं, लेकिन quite right भी नहीं। एक file में inconsistent error handling। एक database query जो काम करती है लेकिन poorly scale करती है। एक नई utility function जो existing एक को duplicate करती है क्योंकि agent को पता नहीं था कि वो exist करती है।

इनमें से कोई भी failure diff review में visible नहीं है। ये तभी visible होते हैं जब तुम समझते हो कि agent क्या करने की कोशिश कर रहा था और उसकी intent को उसके execution से compare कर सकते हो।

Diffs काफी क्यों नहीं हैं

Diff textual changes का record है। बस। Human code review के लिए diffs काम करते हैं क्योंकि reviewer pattern recognition और shared context से intent infer कर सकता है। तुम एक colleague को try/catch block add करते देखते हो और जानते हो कि वो पिछले हफ्ते के bug report का error case handle कर रहा है। तुम उसे function rename करते देखते हो और जानते हो कि वो team की agreed naming convention follow कर रहा है।

Agent-generated code के साथ, तुम intent infer नहीं कर सकते क्योंकि तुम reasoning process का हिस्सा नहीं थे। यहां है जो 500-line agent diff actually तुम्हें बताता है:

कौन सी files modify हुईं
कौन सी lines add, change, या remove हुईं
नए code की syntactic structure

यहां है जो वो नहीं बताता:

यह approach क्यों चुना गया। Agent ने शायद तीन अलग implementations consider किए। एक choose किया। तुम नहीं जानते क्यों। शायद जो choose किया वो optimal है। शायद वो पहली चीज़ थी जो try की और काम कर गई। Diff से तुम नहीं बता सकते।

कौन से alternatives discard किए गए। अगर agent ने WebSocket subscriptions की जगह polling strategy चुनी, तो क्या यह deliberate architectural decision था या accident? Diff नहीं बताता।

Implementation spec से match करती है या नहीं। तुम्हें spec एक window में और diff दूसरी में खोलकर हर acceptance criterion manually cross-reference करना होगा। ज्यादातर लोग नहीं करते।

क्या test हुआ और कैसे। Diff में शायद नई test files हों। लेकिन क्या agent ने उन्हें run किया? क्या वो pass हुए? क्या वो spec के edge cases cover करते हैं? जानने के लिए तुम्हें branch checkout करके खुद run करना होगा।

Agent scope में रहा या नहीं। शायद task था "login bug fix करो" और agent ने auth middleware भी refactor कर दिया, दो utility functions rename कर दिए, और config schema update कर दिया। ये सब changes isolation में ठीक दिखते हैं। लेकिन ये request नहीं किए गए थे, specify नहीं किए गए थे, और original acceptance criteria के against test नहीं किए गए थे।

यह किसी particular diff tool की समस्या नहीं है। GitHub का review interface, GitLab के merge requests, Gerrit, terminal में git diff। सब तुम्हें वही दिखाते हैं: क्या बदला। Agent output के लिए, "क्या बदला" सबसे कम important सवाल है। Important सवाल यह है: क्या यह change वो करता है जो इसे करना चाहिए था, और कुछ नहीं?

गायब परत: Implementation Narrative

Reviewers को actually agent की reasoning trail चाहिए। Diff नहीं। Implementation की कहानी: agent ने क्या करने की plan बनाई, actually क्या किया, और result कैसे verify किया। इसे implementation narrative कहो।

एक अच्छा implementation narrative पांच सवालों के जवाब देता है:

Plan क्या था? Code लिखने से पहले, agent क्या करने का इरादा रखता था? कौन सी files, कौन सा approach, कौन सा order?
Implementation के दौरान क्या हुआ? Plan codebase के contact में survive कर पाया? कोई surprises, pivots, या scope changes?
Final result क्या था? Diff नहीं। Plain-language summary कि क्या बदला और क्यों।
Verify कैसे किया गया? Specific steps जो agent ने confirm करने के लिए लिए कि implementation काम करती है। "Tests pass" नहीं बल्कि "मैंने acceptance criterion #3 X करके run किया और Y observe किया।"
Reviewer को क्या check करना चाहिए? Agent की अपनी recommendation कि क्या human attention deserve करता है। शायद कोई design decision है जो किसी भी direction में जा सकता है, या performance tradeoff जो second opinion deserve करता है।

इसमें से कुछ भी standard PR workflow में exist नहीं करता। PR description field free text है जो कोई enforce नहीं करता। Agent PRs default से minimal descriptions रखते हैं क्योंकि agent को बोला गया implement करने को, अपनी reasoning document करने को नहीं।

Gap tooling नहीं है। Process है। Review infrastructure exist करती है। जो missing है वो agent intent का structured record है जिसे reviewer diff के against check कर सके।

Plan-Comment-Done Pattern

यहां एक pattern है जो gap close करता है बिना significant overhead add किए। इसके तीन parts हैं: agent code लिखने से पहले plan comment करता है, implement करता है, और finish होने पर structured done report comment करता है।

Step 1: Plan Comment

Agent कोई file खोलने से पहले लिखता है कि वो क्या करने का इरादा रखता है। Numbered steps, जो files touch करेगा, और approach जो लेगा।

PLAN: Fix WebSocket reconnection dropping messages during
server restart.

1. Add a message buffer to hooks/use-websocket.ts that queues
   outbound messages while the connection is in CONNECTING state
2. On successful reconnection, flush the buffer in order
3. Add a 30-second timeout: if reconnection hasn't succeeded,
   surface an error to the user via the toast system
4. Update the existing reconnection test to verify buffer
   behavior

Files: hooks/use-websocket.ts, components/connection-status.tsx

Test: Unit test for buffer queueing/flushing, manual test by
killing the WS server mid-operation and verifying no messages
are lost on reconnect.

Agent को यह लगभग 30 seconds लेता है। Reviewer इसे 2 minutes से कम में पढ़ता है। उन 2 minutes में, तुम ऐसी problems catch करते हो जो diff review में 20 minutes लेतीं:

Scope सही है? (Plan 2 files कहता है। अगर diff 6 touch करता है, तो कुछ drift हुआ।)
Approach sound है? (Reconnect पर flush-on-reconnect वाला message buffer reasonable है। अगर agent ने server से पूरा state reload करने का propose किया होता, तो पहले discuss करना चाहते।)
Steps missing हैं? (Timeout window के दौरान भेजे गए messages का क्या? Drop करने हैं या retry?)

Plan एक lightweight checkpoint है। Review करो, approve करो, और agent shared understanding के साथ आगे बढ़ता है।

Step 2: Implementation

Agent code लिखता है। यहां कुछ नहीं बदलता। लेकिन plan exist करने से, agent के पास एक roadmap है जिसे follow कर सकता है बजाय ad hoc decisions लेने के।

Step 3: Done Comment

जब agent finish करता है, वो structured completion report post करता है। "Done" नहीं। "Feature implement कर दी" नहीं। Actually क्या किया इसका detailed account।

DONE: WebSocket reconnection now buffers outbound messages
during CONNECTING state and flushes on successful reconnect.

Changes:
- hooks/use-websocket.ts: Added messageBuffer ref, queue
  messages when readyState !== OPEN, flush in FIFO order on
  'open' event. Added 30s reconnection timeout.
- components/connection-status.tsx: Shows "Reconnecting..."
  badge during buffer state, switches to error toast after
  timeout.

QA Verification:
1. Start dev server and WebSocket server
2. Open app, verify connection dot is green
3. Kill WebSocket server process
4. Trigger an action that sends a WS message (e.g., update
   a bead status)
5. Restart WebSocket server within 30 seconds
6. Verify: the buffered message is delivered, bead status
   updates in the UI
7. Repeat step 3, but wait >30 seconds before restart
8. Verify: error toast appears after timeout

Acceptance criteria:
- [x] Messages sent during reconnection are not lost (step 6)
- [x] Timeout surfaces user-visible error (step 8)
- [x] No behavior change when connection is stable (step 2)

Commit: f4e2a1b

अब reviewer के पास वो सब है जो चाहिए। Plan पढ़ता है (intent क्या था), done comment पढ़ता है (actually क्या build हुआ और कैसे verify हुआ), फिर full context के साथ diff देखता है। Diff review "यह सब क्या है?" से "confirm करूं कि यह agent ने जो कहा उससे match करता है" में बदल जाता है।

Agent Output के लिए Review Checklists

Implementation narrative के साथ भी, तुम्हें systematic approach चाहिए। यहां एक checklist है जो मैं Claude Code output review करते समय use करता हूं। यह per review 5-10 minutes लेती है और उन categories के bugs catch करती है जो diffs alone miss करते हैं।

Spec alignment:

क्या implementation spec के हर acceptance criterion को address करती है?
क्या ऐसे changes हैं जो spec ने जो मांगा उससे आगे जाते हैं?
क्या done comment हर criterion को verification step से map करता है?

Scope containment:

क्या agent ने सिर्फ plan में listed files modify कीं?
अगर additional files touch कीं, तो stated reason है?
क्या "cleanup" changes (renames, reformats, refactors) हैं जो task का हिस्सा नहीं थे?

Test coverage:

नए behavior के लिए नए tests exist करते हैं?
क्या tests actually सही चीज़ test कर रहे हैं? (Agents कभी-कभी ऐसे tests लिखते हैं जो trivially pass करते हैं क्योंकि वो mock test करते हैं, implementation नहीं।)
क्या agent ने claim किया कि tests run किए? Evidence है?

Architectural consistency:

क्या changes codebase के existing patterns follow करते हैं?
क्या नई abstractions हैं जो existing ones duplicate करती हैं?
क्या error handling strategy project के बाकी हिस्से से match करती है?

Dependency awareness:

अगर agent ने dependencies add कीं, क्या वो justified हैं?
क्या changes existing functionality break करते हैं? (Modified modules import करने वाली files check करो।)
अगर task की other tasks से dependencies हैं, क्या वो dependencies resolved हैं?

यह checklist किसी भी code review tool के साथ काम करती है। Post-it पर print करो, PR template में डालो, या CLAUDE.md में build करो ताकि agent को पता हो किस standard पर measure होगा। Point specific items नहीं हैं। "Looks good to me" की जगह structured protocol होना, यह point है।

Review Surface के रूप में Beads

Plan-comment-done pattern को रहने की जगह चाहिए। अगर plans और done comments Slack messages, PR descriptions, और terminal output में बिखरे हैं, तो spec, plan, implementation, और verification के बीच connection खो जाता है।

यह वो problem है जो beads solve करता है। Beads एक open-source, Git-native issue tracker है जहां हर "bead" एक task का पूरा lifecycle carry करता है: description के रूप में spec, comments के रूप में agent plans, comments के रूप में done reports, और comments के रूप में QA results। सब एक entity से attached, searchable, और permanent।

bd CLI के साथ review workflow ऐसा दिखता है:

Spec के साथ task create करो:

bd create --title "Fix WebSocket reconnection message loss" \
  --description "## Problem
Messages sent during WebSocket reconnection are silently
dropped...

## Acceptance Criteria
1. Messages queued during CONNECTING state are delivered
   on reconnect
2. 30-second timeout surfaces error to user
3. No behavior change when connection is stable" \
  --type bug --priority p1

Agent काम claim करता है और plan post करता है:

bd update bb-f4e2 --claim --actor eng1
bd comments add bb-f4e2 --author eng1 "PLAN: Add message
buffer to WebSocket hook...

1. Queue outbound messages when readyState !== OPEN
2. Flush buffer in FIFO order on 'open' event
3. Add 30s timeout with error toast
4. Update reconnection test

Files: hooks/use-websocket.ts, components/connection-status.tsx"

तुम 2 minutes में plan review करते हो:

bd show bb-f4e2  # Spec + plan comment पढ़ो

अगर plan सही लगता है, agent आगे बढ़ता है। अगर नहीं, तो code लिखे जाने से पहले corrections comment करते हो।

Agent complete करता है और done report post करता है:

bd comments add bb-f4e2 --author eng1 "DONE: WebSocket
reconnection now buffers outbound messages...

QA Verification:
1. Kill WS server, trigger action, restart within 30s...

Acceptance criteria:
- [x] Buffered messages delivered on reconnect
- [x] Timeout error visible
- [x] No regression on stable connection

Commit: f4e2a1b"

bd update bb-f4e2 --status ready_for_qa

QA independently verify करता है:

bd show bb-f4e2  # Done comment के verification steps पढ़ो
# हर step execute करो
bd comments add bb-f4e2 --author qa1 "QA PASS: All 3 criteria
verified. Buffer flushes correctly, timeout fires at 30s,
stable connections unaffected."

पूरी review trail एक जगह है। छह महीने बाद, जब कोई पूछे "WebSocket reconnection के दौरान messages buffer क्यों करता है?", जवाब bead में है: spec problem explain करती है, plan approach explain करता है, done comment बताता है क्या build हुआ, और QA comment confirm करता है कि काम करता है।

जब Terminal Review अपनी सीमा पर पहुंचता है

एक task पर bd show तुम्हें सब देता है। लेकिन जब तुम multiple agents का output कई parallel workstreams में review कर रहे हो, CLI workflow linearly scale करता है: हर task के लिए एक bd show, review ready क्या है देखने के लिए एक bd list, हर plan approve करने के लिए एक bd show।

यहां Beadbox fit होता है। Beadbox एक real-time dashboard है जो तुम्हें workspace में हर task उसके current status, latest comment, और review pipeline में position के साथ दिखाता है। तुम देखते हो कि किन agents ने plans post किए हैं जिन्हें तुम्हारी approval चाहिए। किन्होंने done reports post किए हैं जो review ready हैं। कौन अभी भी in progress हैं। सब live update होता है जैसे agents bd CLI से comments लिखते और statuses change करते हैं।

Plan-comment-done pattern use करने के लिए Beadbox की ज़रूरत नहीं। CLI पूरा workflow handle करता है। लेकिन जब पांच agents simultaneously reviewable output produce कर रहे हों, हर task individually poll करने की जगह review queue एक नज़र में देख पाना pipeline से गुज़रने की speed बदल देता है।

Beadbox beta के दौरान free है, और beads CLI जिस पर यह चलता है open-source है।

Review Problem अपने आप solve नहीं होगा

AI-generated code हमारी review करने की capacity से ज़्यादा तेज़ी से बढ़ रहा है। हमारे पास जो tools हैं वो अलग scale और अलग workflow के लिए बने थे। GitHub PRs, IDE diffs, sophisticated static analysis भी: इनमें से कोई fundamental problem address नहीं करता, जो यह है कि author की intent जाने बिना code review करना intent जानते हुए review करने से dramatically harder है।

Fix better diff tools नहीं हैं। Structured intent है: agent ने क्या plan किया, actually क्या किया, और result कैसे verify किया इसका record। Plan-comment-done pattern तुम्हें यह record देता है बिना significant overhead add किए। Agent plan लिखने में 30 seconds खर्च करता है। तुम review करने में 2 minutes। Agent done report लिखने में 60 seconds। तुम scratch से review करने की जगह full context के साथ diff review करते हो।

पांच principles साथ ले जाओ:

Code से पहले plans मांगो। 30-second plan comment 20-minute review sessions बचाता है। अगर plan गलत है, code exist करने से पहले ठीक करो।
Structured done reports demand करो। "Done" done report नहीं है। Verification steps, acceptance criteria mapping, और commit hashes done report हैं।
Diff के against नहीं, spec के against review करो। Diff दिखाता है क्या बदला। Spec बताती है क्या बदलना चाहिए था। Cross-reference करो।
Scope boundaries enforce करो। अगर agent ने plan से बाहर files touch कीं, यह flag है। Unplanned changes unreviewed changes हैं।
Review को judgment नहीं, protocol treat करो। Checklist intuition से ज्यादा bugs catch करती है। "Looks good to me" review नहीं है।

Agents और तेज़ होते रहेंगे। Diffs और बड़े होते रहेंगे। सवाल यह है कि तुम्हारा review process उनके साथ scale करता है, या तुम अभी भी 600-line diffs पर squint करके best hope कर रहे हो।

अगर तुम इस तरह के workflows build कर रहे हो, तो Beadbox को GitHub पर star दो।

AI कोड रिव्यू टूटा हुआ है। यह है जो गायब है।