Handbooks क्या है?
एक कोडबेस अंदर, दो handbooks बाहर — एक narrated documentation site जो आपकी टीम पढ़ती है, और एक location index जिससे आपका coding agent route करता है। एक ही parsed नक्शे से, कोड के साथ हमेशा अद्यतन।
एक कोडबेस अंदर, दो handbooks बाहर।
Handbooks आपके कोड के एक ही नक्शे को दो बार लिखता है, क्योंकि इसके दो बिल्कुल अलग पाठक हैं:
📖 इंसानों के लिए handbook
stage-दर-stage narrated documentation site — search, theme, deep links — आपके कोड से generated, file:// से सीधे खुलती है। यह आप पढ़ते हैं।
🤖 AI के लिए handbook
machine के लिए बना location index: file→stage routing tables, per-function call facts, llms.txt, और installable SKILL package। इसे आपका coding agent पढ़ता है।
नीचे वही तथ्य हैं — parser से बना call graph — इसलिए दोनों कभी असहमत नहीं हो सकते। एक narrative और navigation के लिए, दूसरा routing और staleness detection के लिए अनुकूलित है।
समस्या, साफ़ शब्दों में
आपके पास एक repository है। वह इतनी बड़ी है कि न आपके दिमाग़ में समाती है, न किसी context window में।
किसी coding agent से कहिए "failed uploads को तीन बार retry करो" — और वह पूरे भरोसे के साथ उस एक upload function को patch कर देगा जो उसे मिल गया, और छोड़ देगा: retry-policy वाला constant, batch worker में मौजूद mirrored implementation, attempts गिनने वाला metric, और पुराने behaviour को assert करने वाला test।
यह reasoning की विफलता नहीं है। यह routing की विफलता है। Agent ने कोई map देखा ही नहीं।
एक वाक्य में पूरी बात
Handbooks आपका code एक असली parser से पढ़ता है, उसका एक map बनाता है, वह map agent को location index के रूप में सौंपता है — summary के रूप में नहीं — और code के बदलते रहने पर map को current रखता है।
आगे कुछ भी पढ़ने से पहले इसे चलाकर देखिए
अगर यह चलता ही नहीं, तो नीचे लिखी किसी बात के कोई मायने नहीं। इसमें लगभग तीस सेकंड लगते हैं, शून्य tokens खर्च होते हैं, और किसी API key की ज़रूरत नहीं पड़ती:
git clone <this repo> && cd handbooks
pnpm install && pnpm build
pnpm demopnpm demo एक bundled sample project पर, bundled mock LLM server के सहारे, पूरी toolchain
चलाता है। ख़त्म होने पर आपकी disk पर एक rendered handbook, एक HTML site, एक agent locator
index और एक validated SKILL package मौजूद होगा।
जिन तीन विचारों पर यह टिका है
1. Facts parser से आते हैं, model से नहीं
Handbooks हर source file को tree-sitter से parse करता है
और एक typed call graph बनाता है: functions, methods, self/attributes/parameters/imports
के ज़रिये resolve हुए call edges, आपके code से बाहर जाने वाली calls, और वे calls जो resolve
नहीं हो सकीं — उन्हें अपनी अलग file में quarantine किया जाता है, उनके बारे में कभी अंदाज़ा नहीं
लगाया जाता।
जिन files को यह पढ़ ही नहीं सका या parse ही नहीं कर सका, वे भी इसी तरह quarantine होती हैं — ऐसा gap जिसे आप गिन सकते हैं, न कि जो चुपचाप ग़ायब हो जाए।
यह layer कभी किसी LLM को नहीं छूती। दो बार चलाइए, दोनों बार वही graph मिलेगा।
2. Prose facts के ऊपर की परत है, और labelled है
Human-readable हिस्सा एक LLM लिखता है: कोई file किसलिए है, कोई subsystem आपस में कैसे जुड़ा है, कौन-सा state किन stages के आर-पार बहता है। यह हमेशा graph से बँधा रहता है, और जहाँ यह विफल होता है, वहाँ भी structure ship होता है — खाली description के साथ।
गढ़े हुए वाक्य से छूटा हुआ वाक्य बेहतर है।
3. Map routing के लिए बना है, पढ़ने के लिए नहीं
Output आपके code की summary नहीं है। यह एक ऐसा index है जो इस सवाल का जवाब देता है — "इस बदलाव को किन files, functions और state को छूना पड़ेगा?" — जिनमें बिखरे हुए, ग़ैर-ज़ाहिर हिस्से भी शामिल हैं। इसके बाद planner उसी index से route करता है, मिले हुए हर address पर असली source पढ़ता है, और इतना byte-exact edit plan निकालता है कि उसे यांत्रिक ढंग से apply किया जा सके।
एक run से आपको क्या मिलता है
| Output | किसके लिए |
|---|---|
| Markdown handbook — overview, stage index, हर stage का एक page, state-register table | इंसान |
Multi-page HTML site — sticky TOC, breadcrumbs, theme toggle, file:// पर भी चलती है | इंसान |
| एक self-contained HTML page, जिसे आप email कर सकते हैं | इंसान |
Agent index — symbol → path:line-line, file और call tables, grep recipes | agents |
llms.txt + llms-full.txt | agents |
| हर file के content hash वाला SKILL package, ताकि drift detect किया जा सके | agents |
यह किसके लिए है
| आप हैं… | आपको मिलता है… |
|---|---|
| ऐसे engineer जिन्हें अभी-अभी 200k-line की service विरासत में मिली है | Stage-दर-stage ऐसा walkthrough जो सचमुच पढ़ा जा सके, साथ में share करने लायक़ HTML site |
| बड़ी repo पर coding agent चलाने वाले | ऐसा SKILL package जो agent का "चीज़ें कहाँ हैं" का अंदाज़ा लगाना बंद कर देता है |
| लोगों को onboard कराने वाले team lead | ऐसा documentation जो सड़ने के बजाय regenerate होता है |
| Polyglot monorepo के maintainer | 18 भाषाओं पर एक ही pass, हर भाषा के लिए disclosed analysis fidelity के साथ |
इसकी क़ीमत क्या है
- Node.js ≥ 20.11 और pnpm। पूरा install बस इतना है। कोई native compilation नहीं, कोई
Python नहीं, कोई
node-gypनहीं — parsers WebAssembly हैं। - LLM phases के लिए एक OpenAI-compatible endpoint। Hosted OpenAI, Azure, vLLM,
Ollama, LiteLLM, कोई internal proxy — जो भी
/v1/chat/completionsबोलता हो। यह आपकी अपनी मशीन पर चलता हुआ model भी हो सकता है। handbook analyzeके लिए बिल्कुल कुछ नहीं — और सबसे पहले आपको यही command चलानी चाहिए।
क्या मेरा code इमारत से बाहर जाता है?
Phase 1 पूरी तरह local है। Phase 2 और 3 file contents उसी endpoint को भेजते हैं जिसे आपने configure किया
है — जो localhost भी हो सकता है। और कुछ बाहर नहीं जाता, और --max-chars-per-file तय करता है कि किसी एक file
का अधिकतम कितना हिस्सा कभी भेजा जाएगा। देखें trust model।
आगे कहाँ जाएँ
यह क्यों मौजूद है
Routing की समस्या, और codebase की summary बना देना उसे क्यों हल नहीं करता।
Generation कैसे काम करता है
पाँच phases, हरेक की लागत, और किसी एक के विफल होने पर क्या degrade होता है।
Configuration
Flags, env vars, .env cascades और handbook.config.yaml — एक ही registry।
Troubleshooting
वे चीज़ें जो वाक़ई गड़बड़ होती हैं, और उनके बारे में क्या करना है।