Skip to main content

Agentic Engineering की बुनियाद: 45-minute crash course

8 concepts, वास्तविक इस्तेमाल का 80%

Prerequisite: Agentic Coding Crash Course. वह पेज tools सिखाता है (Claude Code, OpenCode, plan mode, CLAUDE.md, skills, MCP, hooks)। यह पेज वह discipline सिखाता है जिसके साथ आप उन्हें इस्तेमाल करते हैं। दोनों एक-दूसरे को पूरा करते हैं: discipline के बिना tools vibe code पैदा करते हैं; tools के बिना discipline theory रह जाती है।

"Code is not cheap. Bad code is the most expensive it has ever been." Matt Pocock

"Vibe coding is about raising the floor for everyone in terms of what they can do in software. Agentic engineering is about preserving the quality bar of what existed before in professional software." Andrej Karpathy

Industry में एक narrative खुला घूम रहा है: AI नया paradigm है, इसलिए पुराने engineering rules अब लागू नहीं होते; specifications नया source code हैं; model compiler है; diff मायने नहीं रखता, बस program behave करे। यह बात आराम देती है, और गलत है।

इस chapter की thesis, और इस किताब के हर Digital FTE की throughline, इसका उल्टा है। AI युग में software fundamentals पहले से ज़्यादा मायने रखते हैं। वजह भावनात्मक नहीं, mechanical है। आप जो interface design करते हैं, agent उसी से सीखता है; आप जो names चुनते हैं, वही names वह दोबारा इस्तेमाल करता है; आप जो boundaries खींचते हैं, वही boundaries वह मानता है। साफ़, अच्छी तरह tested codebase में वही agent, उलझे हुए codebase की तुलना में कई quality tiers ऊपर का code बनाता है। Architecture अब सिर्फ़ code की property नहीं है; यह agent का input है। खराब code खराब agents देता है। अच्छा code ऐसे agents देता है जो चौंकाने लायक competent लगते हैं।

यह chapter वह workflow सिखाता है जो उस competence को repeatable बनाता है: seven-stage pipeline (idea → grilling → PRD → issues → implementation → review → QA) जिसे छोटे, composable Skills से implement किया जाता है और जो Claude Code और OpenCode में एक जैसा काम करता है। एक tool के लिए लिखे गए Skills, specs, और architectural patterns दूसरे में बिना बदलाव के drop हो जाते हैं। Method constant है। Tool variable है।

Chapter के अंत तक आप यह कर पाएँगे:

  1. vibe coding ↔ agentic engineering spectrum पर अपनी जगह पहचानना और अपने काम के stakes के हिसाब से discipline चुनना।
  2. AI coding के छह failure modes diagnose करना और हर एक का cure apply करना।
  3. Claude Code या OpenCode में पूरा grill → PRD → vertical-slice issues → AFK implementation loop चलाना।
  4. ऐसा SKILL.md लिखना जिसे agent सिर्फ़ ज़रूरत पड़ने पर load करे, हर turn पर tokens खर्च न करे।
  5. Codebase को "shallow modules" से "deep modules" में refactor करना ताकि AI feedback loops सच में काम करें।
  6. Working vocabulary को fluently इस्तेमाल करना: smart zone, dumb zone, clearing, compaction, handoff, AFK, tracer bullet, design concept, grilling, jagged intelligence.

Pipeline एक नज़र में​

Theory से पहले, chapter जिस operating shape को सिखाता है वह यहाँ है। सात stages, पाँच Skills, flow की एक दिशा। आगे की हर section या तो किसी row को समझाती है या उसे code में दिखाती है।

#Stageक्या होता हैInput → OutputSkillSection
1Idea → Aligned conceptAgent आपसे Socratic interview करता है जब तक design shared न हो जाएwish → design conceptgrill-me§6.1
2Concept → DestinationConversation को PRD में synthesise करता हैconversation → PRDto-prd§6.2
3PRD → BacklogPRD को vertical-slice tickets में बाँटता हैPRD → tracer-bullet issuesto-issues§6.3
4Issue → Sliceएक slice implement करता है, test-firstissue → reviewable difftdd§6.4
5Slices → Drained backlogAFK loop sandboxes के अंदर queue drain करता हैissues → PRs(orchestrator)§6.5
6Diff → DecisionHuman diff पढ़ता है, QA run करता हैPR → merge or new issue(taste, not automated)§6.6
7Codebase health, ongoingShallow modules खोजता है; deepenings propose करता हैcodebase → RFCimprove-codebase-architecture§7.4

Stages 1-3 day shift हैं: human in the loop. Stages 4-5 night shift हैं: agent sandbox में AFK चलता है। Stage 6 वापस day shift है। Stage 7 weekly cron पर चलता है और stage 3 में नए issues feed करता है। पूरी pipeline Claude Code और OpenCode में identically चलती है।

Programming में नए हैं? पहले यह पढ़ें।

यह chapter मानता है कि आपने पहले code लिखा है, git इस्तेमाल किया है, test suite run किया है, और pull request खोली है। अगर ये familiar हैं, तो यह box छोड़कर आगे बढ़ें।

अगर ये अभी familiar नहीं हैं, तब भी chapter conceptual map की तरह पढ़ने लायक है। आपको मिलेगा: workflow की shape, AI-coding conversations समझने के लिए vocabulary, common failures की diagnostic catalogue, और वह architectural philosophy जो agents को real codebases में अच्छा काम कराती है। आप अभी example code run नहीं कर पाएँगे; उसके लिए पहले कुछ हफ्तों की programming foundations चाहिए। ईमानदार रास्ता यह है: map के लिए इस chapter को एक बार पढ़ें, prerequisites सीखें, फिर लौटकर code follow करें।

Conceptual sections follow करने के लिए bare-minimum vocabulary:

  • Repo (repository का छोटा रूप): project का code folder, जिसे git track करता है।
  • Branch: repo का parallel version जहाँ आप main code को affect किए बिना experiment कर सकते हैं। Worktree related concept है: disk पर repo की copy, जो branch से attached होती है।
  • Commit: changes का saved snapshot, जिसके साथ छोटा message होता है।
  • Pull request (PR): review के लिए submit किया गया proposed change, main branch में merge होने से पहले। Chapter के stage 6 में यही चीज़ humans review करते हैं।
  • Test / test suite: ऐसा code जो दूसरे code की correctness check करता है और automatically run होता है। "Tests pass" का मतलब checks green आए।
  • Sandbox (या container): isolated environment, sealed mini-computer जैसा, जहाँ agent run कर सकता है, files लिख सकता है, और आपके बाकी system को छुए बिना चीज़ें तोड़ सकता है।
  • Token: text की वह unit जिसे language model process करता है। Average में लगभग word का 3/4 हिस्सा। 100k-token context window में करीब 75,000 words आते हैं।
  • Terminal / shell / bash: computer पर commands run करने का text-based तरीका। इस chapter में $ से शुरू होने वाली lines वे commands हैं जिन्हें आप terminal में type करते हैं।

1. Vibe Coding से Agentic Engineering तक​

दो चीज़ें बहुत पास-पास बदली हैं। पहली ने दूसरी को ज़रूरी बनाया।

1.1 Software 3.0: नया computing paradigm​

Andrej Karpathy software को तीन eras में बताते हैं। Software 1.0 वह है जो अधिकांश engineers ने अपने career में लिखा: explicit code, CPU द्वारा execute होता हुआ, structured data पर काम करता हुआ। Software 2.0 learned weights का era है: branching logic लिखने के बजाय datasets curate करके और neural networks train करके programming करना। Software 3.0 वह era है जिसमें हम अब हैं: prompting से programming, जहाँ LLM एक तरह का programmable computer है, और context window में आप जो डालते हैं वही उस पर आपका lever है।

Eras के बीच जो बदलता है वह artifact है जिसे आप produce करते हैं। 1.0 में artifact executable code था। 3.0 में artifact increasingly agent के लिए लिखा गया text है। जब OpenCode अपना installer ship करता है, तो वह bash script ship नहीं करता; वह natural language का paragraph ship करता है जिसे coding agent में paste करना है। Agent environment पढ़ता है, loop में debug करता है, और working install तक पहुँचता है। Installer अब program नहीं रहा; वह Skill है।

यह generalise होता है। Humans के लिए लिखी documentation ("इस URL पर जाएँ, Settings click करें...") agents के लिए लिखी documentation बन जाती है ("यह अपने coding agent को दें और वह आपका project configure कर देगा"). UIs अब अकेला interface नहीं हैं; agent हर उस system का second-class user बन जाता है जिसे आप build करते हैं, और हर उस system का भी जिस पर आप depend करते हैं। Agent-native infrastructure (APIs, docs, tooling, और deployment pipelines जिन्हें पहले agents के लिए design किया गया हो) अगली platform layer है।

यह chapter Software 3.0 में operate करने के बारे में है। Skills (§5) 3.0 artifacts हैं। PRDs और tickets (§6) 3.0 artifacts हैं। AGENTS.md और CONTEXT.md files (§3, Failure 2) 3.0 artifacts हैं। Code itself increasingly इन सबके downstream है।

1.2 Vibe coding floor उठाती है; agentic engineering ceiling बचाती है​

Karpathy ने vibe coding term भी coin किया: agent को code लिखने देना, diff पढ़े बिना output accept करना, और program runs करता है या नहीं, उससे judge करना। Vibe coding real है, useful है, और रहने वाली है। इसी से non-programmer weekend में useful tool ship करता है; Karpathy इसी तरह MenuGen बनाने का वर्णन करते हैं, उनका side project जो restaurant menu photos को rendered dish images वाले menus में बदलता है। Vibe coding software में individual क्या बना सकता है, उसकी निचली सीमा उठाती है। उस floor-raise के economic consequences बड़े हैं, और mostly अच्छे हैं।

अब इसके ऊपर दूसरी discipline उभर रही है: agentic engineering। जहाँ vibe coding floor उठाती है, agentic engineering ceiling बचाती है: professional software का quality bar। Agent typing का ज़्यादातर काम करता है; security, data integrity, maintainability, contracts, और user experience की जिम्मेदारी आपकी रहती है। Vibe coding vulnerabilities introduce नहीं करती; उसे carelessly इस्तेमाल करने वाला engineer करता है। Typist बदल गया इसलिए bar नहीं बदलता।

Vibe codingAgentic engineering
Goalक्या build किया जा सकता है, उसका floor उठानाProfessional quality का ceiling बचाना
Reviewerअक्सर कोई नहीं; चल रहा है या नहीं, उससे judgeHuman diff पढ़ता है; automated review ऊपर से
ArchitectureAgent जो emit करेEngineer design करता है; agent implement करता है
TestsOptionalNon-negotiable; critical path पर TDD
Codebase healthDrift acceptSchedule पर refactor; modules deepen
Failure handling"मेरे लिए काम करता है"Reproducible; tested; explained
Right settingSide projects, prototypes, throwaway toolsProduction systems, regulated work, anything multi-user

इस chapter के principles और workflows agentic engineering की discipline हैं, vibe coding की freedom नहीं। जब आप ऐसा Digital FTE बनाते हैं जिस पर organisation payroll, customer escalations, या financial reconciliation के लिए भरोसा करेगा, vibe coding malpractice है। आपको floor और ceiling चाहिए: raised throughput और preserved quality।

Mediocre agentic engineer और strong agentic engineer के बीच का gap पुराने "10× engineer" gap से बहुत बड़ा है। Karpathy: "10× is not the speed-up you gain. People who are very good at this peak a lot more than 10× from my perspective right now." उस gap को close करना इस chapter का काम है।

2. हर coding agent को मिलने वाली तीन constraints​

Coding agent कोई magical engineer नहीं है; वह harness में wrapped model है। उस pairing की तीन properties हमारे ऊपर बनाए हर workflow की shape तय करती हैं: finite attention budget, persistent state का अभाव, और jagged capability profile।

2.1 Smart zone और dumb zone​

जब model अगला token predict करता है (text का chunk, लगभग English word का तीन-चौथाई), तो वह context window में पहले से मौजूद हर दूसरे token को weigh करता है। हर token के पास finite attention budget है: बाकी पर खर्च करने के लिए fixed share of influence. N tokens वाली window में लगभग N² attention relationships उस fixed budget के लिए compete करते हैं।

Consequence non-negotiable है। Session के शुरू में agent अपनी smart zone में होता है: sharp, focused, recall अच्छा। जैसे session बढ़ता है, हर token का signal competitors से dilute होता जाता है। Agent dumb zone में drift करता है: ऊपर paste किया schema भूलता है, type file में मौजूद न होने वाले fields invent करता है, same name वाले दो variables गलत bind करता है, अपनी earlier reasoning से contradict करता है। Same model, same parameters; बस same plate से खाने वाले ज़्यादा mouths।

Practical ceiling, current frontier models में, चाहे marketing 200k या 1M context window claim करे, coding work के लिए advertised window से काफी नीचे बैठती है। Practitioner reports roughly 100k tokens को वह waterline मानती हैं जहाँ drift दिखना शुरू होता है, लेकिन exact number shape से कम important है: advertised window के किसी fraction से आगे आपको ज़्यादा capability नहीं मिली; आपको पैसे खर्च करने के लिए ज़्यादा dumb zone मिली है। Larger windows long documents पर retrieval में मदद करती हैं; वे code के लिए reasoning horizon को उतने ही factor से extend नहीं करतीं।

Token usage:    0k ────────── 50k ────── 100k ────── 200k ────── 1M
Quality:        ████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░
                ↑                  ↑
                smart zone         dumb zone begins

Concretely, real session में transition कैसा दिखता है? Roughly ऐसा:

turn  5  → you paste users.ts schema (8 fields: id, email, name, ...)
turn  9  → agent uses User.email correctly
turn 23  → agent builds a route, refers to User.id, all good
turn 47  → context is now ~80k tokens
turn 52  → agent writes  user.emailAddress  ← field doesn't exist
turn 55  → agent invents user.preferences   ← also not in the schema
           ⇒ smart zone exited.
           ⇒ /clear, re-paste schema in a fresh session, continue.

Turn 52 पर वही model, वही prompt है जो turn 9 पर था। सिर्फ़ attention budget बदला। Cure push through करना नहीं है। हर unit of work को smart zone में fit होने लायक size दें, और जब एक unit done हो जाए, session फेंक दें और नया start करें।

2.2 Memento problem​

Models stateless होते हैं। वे model provider requests के बीच कुछ carry नहीं करते। Session के अंदर continuity harness द्वारा हर turn पर context फिर से feed करने से आती है; sessions के बीच continuity वह चीज़ है जो memory system ने disk पर लिखी और अगले session start पर reload की।

यह feature है। Agent के बारे में सबसे reliable बात यह है कि context clear करने से वह known-good state में लौट आता है। जो agent अभी चालीस turns dumb zone में drift करता रहा, वही agent /clear के पाँच seconds बाद fresh attention budget के साथ आपका fresh prompt पढ़ेगा और excellent काम करेगा।

जब session bloat हो जाता है, recover करने के दो तरीके हैं:

  • Clearing: session end करें, नया start करें। Total reset.
  • Compaction: previous session summarise करें और summary से नया session seed करें। Lossy.

Most developers पहले compaction चुनते हैं क्योंकि वह कम destructive लगता है। उस instinct पर शक करें: compaction dumb-zone reasoning का कुछ हिस्सा preserve करता है जिसने आपको problem में डाला। Clearing, छोटे written handoff artifact (PRD, ticket, AGENTS.md) के साथ paired हो, तो next session हर बार same starting state पाता है। Predictable starts predictable finishes देते हैं।

Working principle. Agent को Memento के protagonist जैसा treat करें। उसकी भूलने की आदत के आसपास plan करें। हर important fact environment में survive करे (AGENTS.md, CONTEXT.md, Skill, ticket), chat history में नहीं।

2.3 Jagged intelligence​

पहली दो constraints इस बारे में हैं कि agent कितना attend कर सकता है। तीसरी इस बारे में है कि वह किस चीज़ में अच्छा है, और यही engineers को सबसे ज़्यादा चौंकाती है।

LLMs jagged हैं। वे uniformly smart नहीं होते; कुछ domains में sharp peak करते हैं और दूसरों में stagnate करते हैं, और यह human को task कितना कठिन लगता है उससे कम ही correlate करता है। State-of-the-art model hundred-thousand-line codebase refactor कर सकता है या zero-day vulnerability खोज सकता है, और उसी session में आपको पचास metres दूर car wash तक drive करने के बजाय walk करने को कह सकता है। दोनों abilities सिर्फ़ इस बात से जुड़ी हैं कि labs ने किन RL environments पर train किया।

Frontier models को reinforcement learning से heavily train किया जाता है उन tasks पर जहाँ output verifiable हो: checkable answers वाले math problems, compile होकर tests pass करने वाला code, formal proofs। Clean reward signal होने से model उन circuits के अंदर brilliantly सीखता है। उनके बाहर वह pre-training intuition पर operate करता है, बिना comparable feedback के जो उसे sharpen करे। Capability profile mountain range जैसा दिखता है जिसमें deep valleys हैं: competitive coding और code refactoring पर peaks, physical-world distances वाली common-sense planning पर valley।

capability
   │
   │      ╱╲           ╱╲
   │     ╱  ╲    ╱╲   ╱  ╲
   │    ╱    ╲  ╱  ╲ ╱    ╲     ╱╲
   │   ╱      ╲╱    ╲╱      ╲   ╱  ╲
   │  ╱                      ╲ ╱    ╲___
   └────────────────────────────────────────► task
       code   refactor  math       car-wash    common-sense
                                   walking     physical reasoning

Jagged-intelligence constraint के चार operational implications हैं।

पहला, code lucky domain है। आप पूरी surface के सबसे deep peaks में से एक पर काम कर रहे हैं, इसलिए नहीं कि coding intrinsically आसान है, बल्कि इसलिए कि labs ने इसे economically prioritise किया और heavily train किया। इसे अच्छी किस्मत समझें, यह evidence नहीं कि model "intelligent" है। इस peak के बाहर वही model उन बातों पर confidently wrong हो सकता है जो बच्चा भी सही समझे।

दूसरा, आपके feedback loops आपको verifiable circuits में रखते हैं। Static types, automated tests, lints, और compile errors वही reward signal हैं जिनके against model train हुआ। जब agent आपके tests run करता है और उन्हें fail होते देखता है, वह उसी feedback shape में operate कर रहा होता है जिसने training के दौरान उसकी strongest behaviours बनाई। उन signals के बिना वह बिना correction के pre-training intuition पर वापस है। यही Failure 3 और tdd Skill के पीछे की deeper why है: tests सिर्फ़ bugs नहीं पकड़ते; वे agent को peak पर रखते हैं।

तीसरा, आपको पता होना चाहिए कि आप किस circuit में हैं। जब agent ऐसा कुछ करता है जो junior engineer भी न करे, अक्सर वजह यह होती है कि आप peak से हटकर ऐसे region में चले गए हैं जहाँ labs ने train नहीं किया। "Why would you cross-reference users by email instead of by an explicit user_id?" Karpathy पूछते हैं, अपने MenuGen project में agent को ठीक ऐसा करते देखने के बाद। Agent third-party services में identity modelling के strongest circuits से बाहर था। Fix better prompt नहीं था; Karpathy ने explicit architectural guidance देकर हस्तक्षेप किया।

चौथा, fresh start करते समय stack ऐसा चुनें जो peak के अंदर land करे। Jagged map languages और frameworks में symmetric नहीं है। Boris Cherny बहुत matter-of-fact हैं कि Claude Code TypeScript और React में क्यों बना है: "It's very on distribution for the model." जब बाकी constraints allow करें, mainstream choices prefer करें: niche languages के बजाय Python और TypeScript, exotic stores के बजाय Postgres, hand-rolled चीज़ों के बजाय popular frameworks। आप वह technology नहीं चुन रहे जो आप अकेले लिखते; आप वह चुन रहे हैं जो आपकी agent workforce अच्छी तरह लिखती है। Long tail catch up करेगी; तब तक, on-distribution choices years of effective leverage खरीदते हैं।

जानवर बनाम भूत। Karpathy LLMs को भूत बताते हैं, जानवर नहीं: data और reward से shaped statistical simulations, evolution से shaped biological intelligences नहीं। Consequence: agent पर चिल्लाना उसे improve नहीं करता; sympathy उसे improve नहीं करती; "think step by step" dormant cognition नहीं जगाता। जो काम करता है वह है agent को peak पर रखना (clear context, verifiable feedback, well-named code, precise spec) और trained behaviour को fire होने देना। Agent psychology को personality नहीं, physics समझें।

3. AI coding के छह failure modes​

तीन constraints predictable failures पैदा करती हैं। छह failures इतने आम हैं कि उन्हें closed catalogue की तरह treat किया जा सकता है। नीचे की table diagnostic है; उसके बाद के paragraphs हर row को symptom, root cause, और cure में expand करते हैं जिसे बाकी chapter Skill के रूप में encode करता है।

#SymptomRoot causeCureSkillWhere
1"Agent ने वह नहीं किया जो मैं चाहता था."आपके और agent के बीच shared design concept नहींकोई asset लिखे जाने से पहले Socratic interview से alignment force करनाgrill-me§5, §6.1
2"Agent बहुत verbose है."Ubiquitous language नहीं; आप और agent same चीज़ों को अलग names देते हैंहर session में load होने वाला domain terms का CONTEXT.md maintain करेंgrill-with-docs§5, §6.1
3"Code काम नहीं करता."Weak feedback loops; agent अंधेरे में code लिख रहा हैLoud environment (types, tests, lints) + TDD red-green-refactortdd§5, §6.4
4"हमने ball of mud बना दी."Shallow modules; agents उन्हें humans से तेज़ produce करते हैंModule design में daily invest करें; periodic deepening passimprove-codebase-architecture§7
5"मेरा brain keep up नहीं कर पा रहा."आप हर line को normal pace के 5× पर पढ़ रहे हैंGray-box principle: interfaces design करें, implementations delegate करें(architectural habit)§7.3
6"मैं build से ज़्यादा code review कर रहा हूँ."Throughput ने bottleneck को review में shift कर दियाReview को automated + human layers में बाँटें; vertical slices diffs छोटे रखते हैंautomated-review (§6.5 की recipe; upstream pack में नहीं)§6.5, §7

Failure 1: "Agent ने वह नहीं किया जो मैं चाहता था."​

सबसे आम failure misalignment है। आपके पास feature की clear picture थी; agent ने थोड़ा अलग कुछ बना दिया; आप दोनों "done" का meaning तक अलग समझते हैं। यह communication problem है, model problem नहीं। Frederick P. Brooks ने The Design of Design में missing चीज़ को design concept कहा: जो build किया जा रहा है उसका shared, ephemeral idea. PRDs, specs, और conversations वे assets हैं जो design concept capture करने की कोशिश करते हैं; उनमें से कोई भी खुद design concept नहीं है।

Cure: किसी भी code या formal asset से पहले design concept को stabilise करें। Technique है grilling: agent आपको Socratically interview करता है, एक decision at a time, design tree की हर branch पर चलता है, हर question के लिए अपनी recommendation propose करता है, जब तक दोनों sides aligned न हों। Section 5 Skill दिखाता है।

Failure 2: "Agent बहुत verbose है."​

Fresh agent आपके project में drop होता है और आपका jargon नहीं जानता। आपका codebase उन्हें lessons कहता है और agent course units कहता है। आपकी team materialisation cascade कहती है और agent वही idea explain करने वाला paragraph लिखता है। आप दोनों एक-दूसरे से चूक रहे हैं और tokens burn कर रहे हैं।

यह वही problem है जिसे domain-driven design ने बीस-plus साल पहले solve किया: ubiquitous language। Project को single shared vocabulary चाहिए जिसे code, tests, conversation, और documentation सभी use करें। Agents के साथ इसका दूसरा benefit है: tighter vocabulary का मतलब ambiguity खोलने में कम thinking tokens और task पर ज़्यादा attention।

Cure: repo root पर project के domain terms वाला CONTEXT.md maintain करें, जो हर session में load हो। Section 5 दिखाता है कि grilling और CONTEXT.md same Skill में कैसे pair होते हैं।

Failure 3: "Code काम नहीं करता."​

आप agent से aligned हुए। आपने clean spec लिखा। Agent ने code produce किया, और code broken है, कभी obviously, कभी silently। Diagnosis लगभग हमेशा weak feedback loops होती है। Agent अंधेरे में code लिख रहा है।

The Pragmatic Programmer outrunning your headlights के खिलाफ warn करती है: ऐसे tasks लेना जिन्हें feedback की रोशनी illuminate नहीं कर सकती। Agents यह लगातार करते हैं, humans से भी बुरा, क्योंकि वे खुशी से thousand lines लिख देंगे और फिर check करेंगे कि उनमें से कोई compile भी करता है या नहीं। Coding agent का effective IQ उसके environment के feedback की quality से bounded है।

Cure: environment को loud बनाएँ, static types, type-checked imports, automated tests, fast lints, pre-commit hook, और visual work के लिए browser access के साथ। फिर test-driven development enforce करें ताकि agent छोटे, deliberate steps ले: failing test, उसे pass कराना, refactor, repeat. §5 में tdd Skill इसे encode करता है।

Failure 4: "हमने ball of mud बना दी."​

Agents हर चीज़ accelerate करते हैं, codebase के unmaintainable होने की rate भी। Intervention के बिना वे shallow modules बनाते हैं (कई tiny files जो कई small functions expose करती हैं, जिनके बीच implicit dependencies thread होती हैं) क्योंकि shallow modules one at a time generate करना आसान है। जो agent अपने codebase को navigate नहीं कर सकता, हर pass में worse code produce करता है। Codebase poison loop बन जाता है।

John Ousterhout, A Philosophy of Software Design में, alternative देते हैं: deep modules। Few large modules जिनके simple interfaces हों और बहुत functionality उनके पीछे hidden हो। Deep modules agents के लिए test करना आसान हैं (test boundary interface है), reason करना आसान है (callers को implementation जानने की ज़रूरत नहीं), और delegate करना आसान है (आप interface design करते हैं; agent implementation लिखता है)।

Cure: module design में हर दिन invest करें (Kent Beck), और periodically improve-codebase-architecture run करके shallow modules खोजें और deepenings propose करें। Section 7 principles को depth में cover करता है।

Failure 5: "मेरा brain keep up नहीं कर पा रहा."​

यह surprising failure mode है, और serious भी। Agents के साथ पहली बार काम कर रहे senior engineers अक्सर report करते हैं कि वे ज़्यादा code ship करने के बावजूद कम नहीं, ज़्यादा tired हैं। Agent normal pace के तीन से पाँच गुना code produce करता है, और engineer whole system को उसी new pace पर अपने head में रखता है। Architectural discipline के बिना cognitive load divide होने के बजाय multiply होता है।

Cure: gray box principle। Module interfaces full attention से design करें; implementation agent को delegate करें; module को उसके tests से बाहर से verify करें, अंदर की हर line पढ़कर नहीं। आप architectural map hold करते हैं; agent bricks भरता है। Section 7.3 इसे expand करता है।

Failure 6: "मैं build से ज़्यादा code review कर रहा हूँ."​

Throughput का flip side. Agent fast ship करता है तो bottleneck code review में shift हो जाता है, और review work उसे fill कर देता है। Cure है review को दो layers में बाँटना: high-throughput automated layer जो routine issues का bulk पकड़ती है, और low-throughput human layer जो उन चीज़ों पर focus करती है जिन्हें automated layer नहीं पकड़ सकती।

Cure: automated-review Skill जो fresh session में run हो, input में सिर्फ़ diff, project के coding standards, और security checklist ले, और human के PR खोलने से पहले structured comment produce करे। इसे pre-merge CI step के रूप में run करें; यह contract regressions, missing tests, common security antipatterns, और project conventions से mismatches पकड़ता है। Human reviewer pre-triaged PR पर आता है, attention taste, product fit, और automated layer द्वारा flagged ambiguous calls के लिए freed होती है। Vertical slices (§6) हर diff छोटा रखते हैं; persistent review loops (§6.5.3) automated reviewer को सिर्फ़ merge time पर नहीं, schedule पर run करने देते हैं। यह human review eliminate नहीं करता; यह human attention को वहाँ relocate करता है जहाँ judgement non-substitutable है।

ये छह failures हैं जिन्हें बाकी chapter order में eliminate करता है।

4. End-to-end workflow​

आगे की हर चीज़ इस skeleton पर टिकी है: पूरे pipeline की shape, Skills और code में उतरने से पहले mind में fixed।

4.1 Day shift / night shift model​

दो तरह का काम। Human-in-the-loop काम में keyboard पर person चाहिए जो questions answer करे और judgement calls ले: alignment, design, taste, QA. AFK ("away from keyboard") काम unattended sandbox में चलता है और सुबह आपको diff दिखाता है: implementation, refactors, test fills.

Pipeline alternate करती है:

flowchart TD
    subgraph DAY1["DAY SHIFT - human-in-the-loop"]
        A[Idea] --> B[Grill]
        B --> C[PRD]
        C --> D[Issues - vertical slices]
    end

    D --> BACKLOG[(backlog of issues)]

    subgraph NIGHT["NIGHT SHIFT - AFK, sandboxed"]
        E[Implementation Loop<br/>TDD per slice] --> F[Automated Review<br/>separate session]
    end

    BACKLOG --> E
    F --> PRS[(review-ready PRs)]

    subgraph DAY2["DAY SHIFT - back to human"]
        G[Human Review<br/>read the diff] --> H[QA] --> I[Merge]
    end

    PRS --> G
    H -. new issues from QA .-> BACKLOG

    classDef human fill:#e8f1ff,stroke:#3b6ea8,color:#0d2a4d
    classDef afk fill:#fff5e6,stroke:#a36a1a,color:#3d2700
    class DAY1,DAY2 human
    class NIGHT afk

हर transition handoff है। हर handoff छोटे, durable artifact (CONTEXT.md, PRD, ticket, diff) से mediated है, long-running session से नहीं। Long-running sessions dumb zone में मरते हैं; durable artifacts हमेशा survive करते हैं। यही architectural insight बाकी सबको काम कराती है।

4.2 "Specs-to-code" की limits​

Specs useful हैं। §6.2 के PRDs specs हैं। §6.3 के issues mini-specs हैं। CONTEXT.md spec है। यहाँ argument blanket rejection नहीं है; narrower है: specs को whole workflow मानने के खिलाफ, जहाँ आप specification लिखते हैं, उसे agent के through compile करते हैं, resulting code ignore करते हैं, और कुछ गलत हो तो spec edit करके recompile करते हैं। Pipeline के एक stage के रूप में specs essential हैं। Closed loop के रूप में जो बाकी pipeline को replace करे, वे दो reasons से break down करते हैं।

Code battleground है। Code के अंदर ऐसी constraints छिपी होती हैं जिन्हें spec ने anticipate नहीं किया: वह existing module जिसके साथ feature integrate होना है, database जो data shape actually लौटाता है, cold cache में ही आने वाला bug. जो spec इन चीज़ों का जवाब नहीं देता, वह हर recompilation के साथ reality से दूर drift करता है, और हर round worse code produce करता है क्योंकि agent unrooted suggestions की लंबी history inherit करता है।

Specs decay होते हैं। March में लिखा gamification-prd.md, July तक ऐसे system का document है जो अब exist नहीं करता: names बदल गए, boundaries move हो गईं, requirements evolve हो गईं। उस spec को "extend" करने के लिए load करता agent एक faithfulness problem inherit करता है, एक line लिखने से पहले।

Right model §4.1 वाला है: specs pipeline के एक stage पर handoff artifacts हैं, system का source of truth नहीं। वे implementation के एक-दो sessions guide करते हैं, फिर retire हो जाते हैं। Code, tests, और CONTEXT.md persist करते हैं।

Karpathy plan mode के बारे में वही observation करते हैं: वह reasoning settle होने से पहले asset produce करने की जल्दी करता है, जबकि सही move है "work with your agent to design a spec that is very detailed" किसी भी code से पहले। Grilling-then-PRD-then-issues pipeline वही दिखती है: plan mode asset तक rush करता है; pipeline पहले design concept तक पहुँचती है और asset उससे निकलता है।

4.3 Vertical slices और tracer bullets​

§4.1 में सबसे important shape decision यह है कि PRD को issues में कैसे split किया जाए। Temptation horizontally slice करने की होती है: database के लिए एक issue, API के लिए एक, UI के लिए एक। यह wrong है। Horizontal slicing में agent को third issue land होने तक end-to-end feedback नहीं मिलता; bugs seams पर accumulate होते हैं; और कोई भी issue दूसरों को stall कर सकता है।

Right shape vertical slice है, एक tracer bullet, Pragmatic Programmer की उस analogy से जिसमें glowing rounds anti-aircraft gunner को दिखाते हैं कि fire कहाँ जा रही है। Tracer shoot करें ताकि aim सही है या नहीं दिखे, फिर fully fire करें यह जानते हुए कि hit होगा।

flowchart LR
    subgraph H["Horizontal slicing - bad<br/>(no integrated feedback until phase 3)"]
        direction TB
        H1[Frontend - phase 3]
        H2[API - phase 2]
        H3[Database - phase 1]
        H1 -.- H2 -.- H3
    end

    subgraph V["Vertical slicing - good (tracer bullets)"]
        direction TB
        V1[Slice 1<br/>F→A→D] ~~~ V2[Slice 2<br/>F→A→D] ~~~ V3[Slice 3<br/>F→A→D] ~~~ V4[Slice 4<br/>F→A→D]
    end

    classDef bad fill:#fde8e8,stroke:#a83838,color:#5a0d0d
    classDef good fill:#e8f5e8,stroke:#3b8a3b,color:#0d3a0d
    class H bad
    class V good

Section 6.3 worked example पर vertical slicing कैसी दिखती है, यह walk through करता है, including कैसे slices के बीच dependency graph parallel execution allow करता है। अभी concept काफी है: हर issue end-to-end path ship करता है; sequencing dependencies से निकलती है, phases से नहीं।

5. Skills as encoded process​

हर cure को reusable, agent-loadable artifact के रूप में encode करना पड़ता है। वह artifact Skill है।

Principle vs. instance. पाँच principles इस pipeline को चलाते हैं: grilling, PRD-synthesis, vertical-slicing, TDD, deepening. हर एक का current best-in-class implementation किसी skill pack में है। Implementations evolve होते हैं; principles नहीं। Community Skills की live registry skills.sh है; Matt Pocock का pack skills.sh/mattpocock पर है और नीचे के worked examples देता है। जब next quarter कोई better grill-me ship हो, instance swap करें; आपकी pipeline में grilling principle नहीं बदलता। Architectural invariant वही है जो §7.3 code level पर सिखाता है: interface stable है; implementation mutable है।

5.1 Skill क्या है, और क्या नहीं है​

Skill (n.): teachable capability जो unit के रूप में bundled होती है (एक task अच्छी तरह करने के instructions और resources), environment में रखी जाती है और context window में सिर्फ़ relevant होने पर load होती है। Progressive disclosure की unit, harness के अंदर।

Skill वह है जिसे agent पढ़ता है; Tool वह है जिसे agent call करता है। Skill कह सकता है "जब user deploy मांगे, bash deploy.sh run करें और gh tool से verify करें": Skill prose है; bash और gh tools हैं।

Skill on-demand भी है। AGENTS.md हर turn load होता है और हर model provider request पर token cost देता है; Skill सिर्फ़ तब load होता है जब agent तय करे कि वह relevant है। जो चीज़ हर turn context में नहीं चाहिए, वह Skill में belongs करती है, AGENTS.md में नहीं। यही progressive disclosure है।

और Skill portable है। वही SKILL.md Claude Code और OpenCode में बिना बदलाव चलता है। Discipline file के साथ travel करती है; harness interchangeable है।

5.2 Skills कहाँ रहते हैं​

दोनों harnesses session start पर well-known directories scan करते हैं, हर SKILL.md की YAML frontmatter पढ़ते हैं, और names/descriptions agent को surface करते हैं। Body तभी load होती है जब agent decide करे कि Skill relevant है।

skills CLI community pack को .agents/skills/ में install करता है, जो cross-tool standard location है। Installed skills की directory ऐसी दिखती है:

project/
└── .agents/
    └── skills/
        └── grill-me/
            └── SKILL.md

Same SKILL.md format दोनों harnesses में unchanged काम करता है। फर्क यह है कि कौन-सी directories कौन सा harness scan करता है, और इससे install का एक step बदलता है।

Claude Code 2.1.141 .claude/skills/<name>/SKILL.md scan करता है (और globally ~/.claude/skills/)। यह .agents/skills/ scan नहीं करता। skills CLI .agents/skills/ में install करता है, और install को .claude/skills/ में तभी link करता है जब वह directory पहले से exist करती हो। इसलिए पहले उसे create करें, फिर install करें:

mkdir -p .claude/skills
npx skills@latest add mattpocock/skills

Install से पहले .claude/skills/ present होने पर हर skill उसमें linked हो जाती है और Claude Code pack discover करता है। (अगर आप पहले install करते हैं और Claude Code /grill-me नहीं find करता, तो वजह missing directory है: .claude/skills/ create करें, फिर install दोबारा run करें।)

Plain language में पूछकर Skill invoke करें ("grill me on this plan"), और agent frontmatter-description match पर उसे load करता है। Claude Code explicit slash invocation भी accept करता है: उस Skill को name से load करने के लिए /grill-me type करें।

एक format, दोनों harnesses, कोई translation step नहीं। Install path ही फर्क है, और वह एक mkdir का फर्क है।

5.3 SKILL.md की anatomy​

SKILL.md के दो parts होते हैं: YAML frontmatter (metadata जिसे harness scan करता है) और markdown body (instructions जिन्हें agent load पर पढ़ता है)।

Matt Pocock के pack का most-starred Skill, grill-me, पूरा यहाँ है: body की सात lines.

---
name: grill-me
description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
---

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Ask the questions one at a time.

If a question can be answered by exploring the codebase, explore the codebase instead.

यह पूरा Skill है, और grill-me उस pack का most-used skill है जिसने GitHub पर tens of thousands stars draw किए हैं। तीन observations generalise होती हैं:

  1. Skills impactful होने के लिए long होना ज़रूरी नहीं। यह essentially तीन sentences है और planning conversation transform कर देता है। Length तभी add करें जब length अपनी जगह earn करे।
  2. Frontmatter real काम कर रही है। Harness agent को body नहीं, description दिखाता है, इसलिए description enough specific होनी चाहिए कि agent सही moments पर load करे। "Use when user wants to stress-test a plan, get grilled on their design, or mentions 'grill me'" "for grilling" से बहुत बेहतर है।
  3. Body agent को second person में address करती है, उसी tone में जिसका इस्तेमाल आप junior collaborator से करते। "Interview me relentlessly." "Ask the questions one at a time." Direct, declarative, no hedging.

More elaborate Skill (to-prd, to-issues, tdd, improve-codebase-architecture) numbered steps, template, और दूसरे Skills के pointers से same shape extend करता है। Principle holds: process encode करें; answer encode न करें।

5.4 पाँच daily principles (और आज के best Skills)​

पाँच principles §4.1 की pipeline stages से one-to-one match करते हैं। हर principle का current best-in-class implementation है: आज installable SKILL.md। नीचे की table most-used pack (Matt Pocock का, skills.sh/mattpocock) reference करती है। हर Skill name canonical SKILL.md से link है; bodies छोटी हैं और पढ़ने लायक हैं।

StageSkillक्या करता है
Idea → Aligned design conceptgrill-meAlignment पहुँचने तक Socratic interview.
Aligned concept → Destination docto-prdConversation को PRD में synthesise करता है, user stories, implementation decisions, और modified modules की list के साथ।
PRD → Backlog of issuesto-issuesPRD को explicit blocking relationships वाले vertical-slice tickets में तोड़ता है।
Issue → Implemented slicetddRed-green-refactor, एक slice at a time.
Codebase health, ongoingimprove-codebase-architectureShallow modules खोजता है; deepenings propose करता है; RFC issue खोलता है।

इनमें से कोई भी run करने से पहले। Matt का pack one-time per-repo bootstrap step expect करता है, setup-matt-pocock-skills, जो repo की issue-tracker config और ## Agent skills block आपके AGENTS.md / CLAUDE.md में scaffold करता है, और docs/agents/ directory setup करता है। Engineering skills इस scaffolding से पढ़ते हैं (और to-prd / to-issues अगर docs/adr/ मौजूद हो तो उससे भी draw करते हैं), इसलिए pack install करने के बाद और पहले to-issues या tdd invocation से पहले setup एक बार run करें।

हर Skill की frontmatter description: वह line है जिसे harness session start पर scan करके decide करता है कि agent को क्या surface करना है। वही description तय करती है कि agent सही moment पर Skill load करेगा या नहीं, इसलिए असली weight उसी पर है। grill-me का full SKILL.md §5.3 में verbatim आता है; बाकी के लिए, हर एक क्या करता है, यहाँ है (installed skills से paraphrased, quoted नहीं):

  • to-prd current conversation को PRD में बदलता है और project के issue tracker पर publish करता है। यह आपको फिर से interview नहीं करता; context में जो already है उसे synthesise करता है।
  • to-issues plan, spec, या PRD को independently grabbable issues में break करता है, vertically sliced with explicit blocking relationships, और हर issue को agent pick-up के लिए ready label करता है।
  • tdd feature build या bug fix के लिए strict red-green-refactor loop चलाता है: पहले एक failing test, pass कराने के लिए just enough code, refactor, repeat, tests internal helpers के बजाय module interfaces पर।
  • improve-codebase-architecture codebase में deepening opportunities खोजता है, CONTEXT.md की domain language और docs/adr/ के decisions से informed, और code modify किए बिना उन्हें propose करता है।

जो reader exact frontmatter चाहता है, वह cat से installed SKILL.md files पढ़े या linked sources खोले; ऊपर की wording faithful summary है, quote नहीं। Summaries एक behaviour explicitly बताती हैं जो reader directly भी देखेगा: to-prd और to-issues दोनों आपके issue tracker में लिखते हैं, सिर्फ़ local file में नहीं।

तीन properties सभी पाँच में generalise होती हैं:

  1. description loading work कर रही है। उसे इतना specific होना चाहिए कि agent पहचाने कब Skill load करना है, सिर्फ़ Skill किस बारे में है नहीं। "Use when..." clauses और explicit negative scope में यही specificity रहती है।
  2. Skills अपनी boundaries name करती हैं। to-prd फिर से interview नहीं करता; improve-codebase-architecture codebase modify नहीं करता। ये negative clauses Skills को compose करने देते हैं, बिना एक-दूसरे पर step किए।
  3. Skills अपनी pairings name करती हैं। tdd implicitly उस issue से paired है जिसे वह implement करता है; to-issues उस PRD से paired है जिसे वह split करता है। Pipeline Skills की chain है, हर एक next को handoff करता है।
Skill loading आपके model की instruction-following पर depend करती है

इस pipeline की architecture (Skills, vertical slices, deep modules, sandboxes) model-agnostic है। इसकी operational reliability नहीं। Frontier-class instruction-follower (Claude Sonnet/Opus, GPT-5-class, Gemini 2.5 Pro) description match से सही Skill load करता है, multi-step Skill body को order में execute करता है, और alignment reach होने पर grilling interview self-terminate करता है। Economy या local model (deepseek-chat, Haiku-class, Llama-70B, most local models) पर ये behaviours degrade करते हैं: Skills trigger miss करते हैं, multi-step sequencing slip होती है, और literal-output contracts (§6.5 का NO_MORE_TASKS signal) टूटते हैं। §2.3 की recall यहाँ भी cure है: कमजोर model पर harder scaffold करें। Description-matching पर rely करने के बजाय Skills को explicitly by name invoke करें, Skill bodies short और declarative रखें, और model को क्या नहीं करना है यह भी उतना ही साफ़ कहें जितना क्या करना है।

Matt Pocock के pack में sixth Skill Failure 2 (verbose agent / no shared vocabulary) का loop close करता है: grill-with-docs. यह grill-me जैसा ही Socratic interview है, लेकिन decisions crystallise होते समय साथ-साथ CONTEXT.md और docs/adr/ Architecture Decision Records update करता है। Matt की Software Fundamentals Matter More Than Ever talk में यह standalone "ubiquitous language skill" के रूप में शुरू हुआ था जो codebase scan करके domain glossary लिखता था; तब से इसे grilling skill में fold कर दिया गया है, इस principle पर कि terminology उस moment पर resolve करना best है जब decision लिया जा रहा हो, separate post-hoc pass के रूप में नहीं। Greenfield design conversations के लिए grill-me इस्तेमाल करें जहाँ अभी project context नहीं है; grill-with-docs तब इस्तेमाल करें जब repo में CONTEXT.md और ADRs हों जिन्हें current रखना है।

पहले अपने Skills build करें; दूसरे के pack की तरफ़ बाद में जाएँ। Best Skill वही है जो आपकी team की process capture करे। mattpocock/skills fork करना great starting point है। Stack own करना, हर Skill पढ़ पाना जिसे आप load करते हैं, यही आपको observability देता है जब कुछ गलत होता है।

6. Pipeline practice में​

यह section workflow end-to-end run करती है worked example पर: course platform में gamification service add करना। Same example एक बार Python में और एक बार TypeScript में build होता है; हर step Claude Code और OpenCode दोनों में चलता है। Point example नहीं है; shape है। Shape एक बार internalise कर लें और language तथा harness details बन जाते हैं।

6.1 Stage 1: Idea को grill करना​

Stakeholder का Slack message:

"Our retention numbers aren't great. Students sign up, do a few lessons, then drop off. I'd love to add some gamification to the platform: points, streaks, levels."

यह spec नहीं है; यह wish है। इसे agent को देकर "build it" कहें तो आपको ऐसा कुछ मिलेगा जो stakeholder के मन से match नहीं करेगा, क्योंकि अभी आप दोनों में से कोई नहीं जानता कि उनके मन में क्या है। grill-me invoke करें।

$ claude
> /grill-me
> Read the Slack message in client-brief.md and grill me on adding gamification.

Agent brief पढ़ता है, existing models (Lesson, Quiz, Enrollment) समझने के लिए codebase explore करता है, और एक-एक करके questions पूछना शुरू करता है, हर question के साथ recommended answer:

Q1. What earns points? My recommendation: lesson completion + quiz pass.
    Skip video-watch events (too noisy, gameable).

Q2. Are points retroactive for existing lesson_progress records?
    My recommendation: yes, backfill once on migration, then live going forward.

Q3. Streak granularity? My recommendation: daily, with a 1-day grace period.

Q4. Level thresholds: linear, quadratic, or hand-tuned?
    My recommendation: quadratic, capped at level 50.
...

Sessions पंद्रह से सौ questions तक कहीं भी रुकते हैं। Session तब end होता है जब agent report करे कि कोई decisions unresolved नहीं रहे और आपके पास stable design concept है। No code, no PRD. Grilling का output chat history है; chat history design concept को explicit बनाती है।

6.2 Stage 2: Conversation से PRD तक​

Design concept stabilise होने के बाद to-prd invoke करें। Skill आपको फिर से interview नहीं करता; यह आप जो already कह चुके हैं उसे Product Requirements Document में synthesise करता है।

> /to-prd

Output fixed template follow करने वाला markdown document है:

# PRD: Course Platform Gamification

## Problem Statement

Students drop off after a handful of lessons. Retention metrics
indicate completion rates ... [synthesised from the brief]

## Solution

Add a points/streaks/levels gamification layer ...

## User Stories

1. As a student, I earn 10 points when I complete a lesson.
2. As a student, I earn 25 points when I pass a quiz.
3. As a student, I see my current streak on the dashboard.
4. As a student, I see my level on my profile.
5. As an admin, I can see aggregate engagement metrics.
   ... [12-20 more, each independently verifiable]

## Modules Touched

- NEW: gamification_service (deep module, owns points + streaks + levels)
- MODIFIED: lesson_progress_service (emits events on completion)
- MODIFIED: dashboard route (reads from gamification_service)
- NEW DB: point_events table, streak_state table

## Implementation Decisions

- Level formula: floor(sqrt(total_points / 50))
- Streak grace: 1 missed day allowed
- Backfill: one-time job at deploy

## Out of Scope

- Leaderboards (separate PRD)
- Push notifications (separate PRD)

Approve करने से पहले PRD में क्या पढ़ें। Drift के लिए skim करें, proofread न करें। Grilling session से आप और agent already design concept share करते हैं, और agent summarisation में excellent है; line-by-line reading dumb-zone work है। अपना attention उन चार जगहों पर focus करें जहाँ summarisation drift कर सकती है: user stories (क्या कोई drop या invent हुई?), modules touched (क्या boundary अब भी discussed चीज़ से match करती है?), implementation decisions (क्या वे grilling के दौरान लिए गए calls से match करते हैं?), और out of scope (क्या boundary creep हुई?)। दो minutes की focused skimming लगभग सभी failures catch करती है; पूरा document पढ़ना वही failures catch करता है और attention दस गुना खर्च करता है।

6.3 Stage 3: PRD से vertical-slice issues तक​

PRD destination describe करता है। Next Skill journey describe करता है: PRD को independently grabbable issues में कैसे break करना है, vertically sliced, with blocking relationships between them.

to-issues run करें। Gamification PRD के लिए यह small Kanban board produce करता है:

┌────────────────────────────────────────────────────────────┐
│ Issue #1 - Award points for lesson completion (E2E)        │
│   blocked by: nothing.       Type: AFK.                    │
│   Touches: schema, service, lesson route, dashboard widget │
└────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────┐
│ Issue #2 - Award points for quiz pass (E2E)                │
│   blocked by: #1.            Type: AFK.                    │
└────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────┐
│ Issue #3 - Streak counter (E2E)                            │
│   blocked by: #1.            Type: AFK.                    │
└────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────┐
│ Issue #4 - Level threshold + UI badge                      │
│   blocked by: #2.            Type: AFK.                    │
└────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────┐
│ Issue #5 - Retroactive backfill of historical lessons      │
│   blocked by: #1.            Type: human-in-the-loop.      │
└────────────────────────────────────────────────────────────┘

कई properties accidental नहीं हैं:

  • Issue #1 working slice ship करता है। अगर team सिर्फ़ #1 merge करके रुक जाए, platform में functioning (minimal ही सही) gamification feature होगा। Horizontal slicing में "phase 1" सिर्फ़ database table produce करता जो कुछ नहीं करती।
  • DAG parallelism allow करता है। #1 merge होने के बाद #2 और #3 parallel sessions में parallel branches पर run कर सकते हैं। दो AFK agents, सुबह तक दो PRs.
  • #5 human-in-the-loop flagged है, AFK नहीं। Backfills historical data touch करते हैं; human हर step देखता है। Type field §6.5 के AFK loop को बताता है कि इसे skip करे।

6.4 Stage 4: Implementation: एक slice पर TDD​

Queue के unblocked top को pick करें: Issue #1. tdd invoke करें। Skill strict red-green-refactor enforce करता है: एक failing test लिखें, उसे fail होते देखें, उसे pass कराने के लिए just enough code लिखें, उसे pass होते देखें, all tests green रहते हुए refactor करें, repeat.

TDD specifically क्यों? दो वजहें।

  1. यह small steps force करता है। TDD के बिना agent छह files का code produce करता है और बाद में उसके आसपास test layer लिखता है। वे tests अक्सर cheat करते हैं; वे behaviour नहीं, implementation exercise करते हैं। TDD में test पहले लिखा जाता है, implementation exist होने से पहले, इसलिए वह agent के लिखे हुए के fit में shaped नहीं हो सकता।
  2. यह हर minute feedback देता है। हर test pass checkpoint है। अगर agent drift करे, next failing test उसे hundred lines garbage produce करने से पहले catch करता है।

Issue #1 के लिए slice दोनों languages में यहाँ है: deep GamificationService module with small interface, wide implementation, और focused test file. tdd Skill working test runner assume करता है: start करने से पहले एक install करें, Python slice के लिए pip install pytest या TypeScript slice के लिए npm install -D vitest, वरना first red step missing implementation नहीं, missing runner पर fail होगा।

यहाँ क्या matter करता है। नीचे का example syntax पढ़े बिना दिखने वाली दो चीज़ें दिखाता है:

  1. Service का public interface tiny है: सिर्फ़ दो methods (award_lesson_completion और total_points)। बाकी सब class के अंदर hidden है। Callers internals तक नहीं पहुँच सकते।
  2. Test सिर्फ़ उन्हीं दो methods को call करता है। Test internal helpers को poke नहीं करता। यह behaviour check करता है जिसे caller देखेगा ("तीन completions के बाद total 30 है"), यह नहीं कि service उसे compute कैसे करता है।

यही shape (small interface, wide implementation, tests at the boundary) §7 में deep module कहलाती है। Python और TypeScript versions line-for-line equivalent हैं।

# gamification/service.py - the deep module's interface

from dataclasses import dataclass
from datetime import datetime
from typing import Protocol


@dataclass(frozen=True)
class PointAward:
    student_id: str
    points: int
    reason: str
    awarded_at: datetime


class PointEventStore(Protocol):
    def append(self, award: PointAward) -> None: ...
    def total_for_student(self, student_id: str) -> int: ...


class GamificationService:
    """Awards and totals points. Streaks and levels live here too,
    but in the same module, so the interface stays small."""

    LESSON_COMPLETION_POINTS = 10

    def __init__(self, store: PointEventStore, clock=datetime.utcnow) -> None:
        self._store = store
        self._clock = clock

    def award_lesson_completion(self, student_id: str) -> PointAward:
        award = PointAward(
            student_id=student_id,
            points=self.LESSON_COMPLETION_POINTS,
            reason="lesson_completion",
            awarded_at=self._clock(),
        )
        self._store.append(award)
        return award

    def total_points(self, student_id: str) -> int:
        return self._store.total_for_student(student_id)
# gamification/test_service.py - written FIRST

from datetime import datetime
from gamification.service import GamificationService, PointAward


class InMemoryStore:
    def __init__(self) -> None:
        self._events: list[PointAward] = []

    def append(self, award: PointAward) -> None:
        self._events.append(award)

    def total_for_student(self, student_id: str) -> int:
        return sum(a.points for a in self._events if a.student_id == student_id)


def test_lesson_completion_awards_ten_points():
    store = InMemoryStore()
    fixed_clock = lambda: datetime(2026, 5, 10, 12, 0, 0)
    svc = GamificationService(store, clock=fixed_clock)

    award = svc.award_lesson_completion("student-42")

    assert award.points == 10
    assert award.reason == "lesson_completion"
    assert svc.total_points("student-42") == 10


def test_multiple_completions_accumulate():
    svc = GamificationService(InMemoryStore())
    for _ in range(3):
        svc.award_lesson_completion("student-42")
    assert svc.total_points("student-42") == 30

यह deep module काम करते हुए है: two-method public interface (awardLessonCompletion, totalPoints) जिसके ऊपर implementation हजारों lines तक grow करने के लिए free है। Claim assert करने के बजाय prove करने के लिए, यहाँ Issue #3 (streak counter) land होने पर क्या होता है।

यहाँ क्या matter करता है। Public interface देखें, lines नहीं। इस slice से पहले service के दो methods थे (awardLessonCompletion, totalPoints)। इस slice के बाद तीन हैं (same दो plus currentStreak)। Implementation काफी grow हुई, streak store, activity log, और date helper के साथ, लेकिन इनमें से कुछ बाहर leak नहीं होता। Callers को एक नया method दिखता है। Existing callers कुछ differently नहीं करते। Existing tests green रहते हैं। New test सिर्फ़ new method को call करता है। Practice में "deep" का मतलब यही है: behaviour grow करता है; surface barely move करती है।

# gamification/service.py - interface gains ONE method, nothing else changes

class GamificationService:
    LESSON_COMPLETION_POINTS = 10

    def __init__(self, store, streaks=None, clock=datetime.utcnow):
        self._store = store
        self._streaks = streaks or InMemoryStreakStore()  # internal detail
        self._clock = clock

    def award_lesson_completion(self, student_id: str) -> PointAward:
        # unchanged signature; internally also updates streak state
        award = PointAward(...)
        self._store.append(award)
        self._streaks.record_activity(student_id, self._clock().date())
        return award

    def total_points(self, student_id: str) -> int:        # unchanged
        return self._store.total_for_student(student_id)

    def current_streak(self, student_id: str) -> int:      # NEW - only addition
        return self._streaks.streak_length(student_id, today=self._clock().date())
# gamification/test_service.py - existing tests untouched; ONE new test added

def test_streak_grows_with_consecutive_daily_completions():
    days = [date(2026, 5, 8), date(2026, 5, 9), date(2026, 5, 10)]
    clock = iter(datetime.combine(d, time()) for d in days)
    svc = GamificationService(InMemoryStore(), clock=lambda: next(clock))

    for _ in days:
        svc.award_lesson_completion("student-42")

    assert svc.current_streak("student-42") == 3

तीन चीज़ें हुईं, और तीनों healthy deep module की diagnostic हैं:

  • Interface एक method से grow हुआ, पाँच से नहीं। Shallow alternative recordActivity, streakLength, streakStore, setActivityCalendar expose कर देता: internal mechanics boundary में leak हो जाते। Deep version callers को exactly वही देता है जो चाहिए (currentStreak) और कुछ नहीं।
  • Existing tests नहीं बदले। वे जिस behaviour को pin करते हैं वह अब भी hold करता है; test file purely additive है। Interface पर testing का benefit यही है।
  • New behaviour को same boundary पर एक test मिला। Streak store, activity log, और date helper directly tested नहीं हैं; वे currentStreak के contract के through indirectly tested हैं, जो right level है।

Next slice (Issue #4, level threshold) same pattern follow करता है: one method added, existing tests untouched, boundary पर one new behaviour test.

6.5 Stage 5: AFK loop​

Backlog में पाँच issues हैं और tdd Skill installed है। आप keyboard पर बैठकर agent को उन्हें grind करते नहीं देखना चाहते। आप system में पाँच tracer bullets parallel push करना चाहते हैं, dinner खाना चाहते हैं, और morning में पाँच PRs review करना चाहते हैं।

AFK loop shell script है: unblocked AFK issues gather करें, clear prompt के साथ agent को दें, sandboxed container के अंदर run करें, queue empty होने तक repeat करें। दो implementations follow करती हैं: minimal bash version (दोनों harnesses के साथ काम करता है) और structured TypeScript orchestrator जो slices parallel run करता है।

6.5.1 Minimal AFK loop (bash)​

यहाँ क्या matter करता है। Script loop में पाँच चीज़ें करती है जब तक कुछ बचा न रहे: (1) folder से सभी open issues पढ़ना; (2) recent commit history पढ़ना; (3) दोनों को clear prompt के साथ agent को hand करना; (4) agent एक issue pick करके implement करता है; (5) queue empty है या नहीं check करना, और अगर है तो stop. Human इस दौरान keyboard पर नहीं है। Script start होती है और खुद चलती है।

#!/usr/bin/env bash
# ralph.sh - the simplest AFK loop. Works with either harness.
# Loops over /issues/*.md, picks the highest-priority AFK issue,
# implements it inside a sandbox, commits, repeats until done.
set -euo pipefail   # bash safety: exit on any error, undefined var, or failed pipe

PROMPT_FILE="${1:-prompts/implement.md}"
ISSUES_DIR="${2:-issues}"

# Two env vars carry the harness difference. AGENT_CMD is the binary;
# AGENT_PERM_FLAG is its skip-approvals flag, which is NOT the same
# string in both harnesses (see the tool-tabs below). Everything else
# in this script is byte-identical across Claude Code and OpenCode.
CMD="${AGENT_CMD:-claude}"
PERM_FLAG="${AGENT_PERM_FLAG:---permission-mode acceptEdits}"

while :; do
  ISSUES=$(cat "$ISSUES_DIR"/*.md 2>/dev/null || true)
  COMMITS=$(git log --oneline -5)

  PROMPT=$(cat "$PROMPT_FILE")

  RESULT=$($CMD $PERM_FLAG <<EOF
$PROMPT

## Open issues
$ISSUES

## Recent commits
$COMMITS
EOF
)

  # Exit only on a line that is *exactly* the sentinel, so the loop
  # does not stop if the agent merely quotes the token in prose.
  if echo "$RESULT" | grep -qx "NO_MORE_TASKS"; then
    echo "queue drained - exiting"
    break
  fi
done
<!-- prompts/implement.md - fed to the agent on every iteration -->

You are operating AFK on the gamification project.

1. From the open issues, pick the highest-priority issue whose
   `Type:` is `AFK` and whose blockers are all closed.
   If none, reply with a line containing only `NO_MORE_TASKS` and stop.
2. Read the PRD it references.
3. Use the `tdd` skill to implement one vertical slice.
4. Run the project feedback loops (typecheck, tests, lint).
   Do not commit if any fail.
5. Commit referencing the issue number and close the issue.

Skills, prompt, और issues दोनों harnesses में byte-identical हैं। फर्क harness binary और उसके skip-approvals flag में है: Claude Code same effect के लिए --permission-mode acceptEdits use करता है, OpenCode --dangerously-skip-permissions। नीचे की दो env vars वह difference carry करती हैं; stdin वाला heredoc दोनों के लिए काम करता है।

AGENT_CMD="claude" \
  AGENT_PERM_FLAG="--permission-mode acceptEdits" ./ralph.sh

6.5.2 Parallel AFK orchestrator (TypeScript)​

Bash version slices sequentially run करता है। Loop पर भरोसा हो जाए तो next leverage point parallel execution है: सभी unblocked issues pick करें, हर issue के लिए एक sandboxed worktree spin up करें, उन्हें concurrently run करें, merge करें। नीचे orchestrator pattern sketch करता है; production-grade implementations Claude Code और OpenCode ecosystems में dedicated sandboxing libraries के रूप में exist करती हैं।

यहाँ क्या matter करता है। तीन ideas; बाकी plumbing है:

  1. Parallel, sequential नहीं। Slice 1, फिर slice 2, फिर slice 3 करने के बजाय orchestrator तीनों को same time पर करता है, हर एक अपने isolated workspace में। Morning में आपके पास one के बजाय three pull requests हैं।
  2. हर parallel run sandboxed है। "Sandboxed worktree" codebase की अलग copy है (git worktree multiple checked-out copies रखने का git का built-in तरीका है) जो container के अंदर run करती है और आपके laptop को damage नहीं कर सकती। Agent कुछ गलत करे तो blast radius एक worktree है।
  3. Reviewer fresh session में separate agent है। अलग agent, अलग (cheaper) model के साथ, सिर्फ़ diff देखता है और project के coding standards से compare करता है। जिस chat ने code लिखा उसी में review करना dumb zone में review करना है।

Code खुद mid-level Node.js script है; Promise.all line पर parallelism होता है।

// orchestrator.ts - parallel AFK loop with sandboxed worktrees
import { spawn } from "node:child_process";
import { readdir, readFile } from "node:fs/promises";

interface Issue {
  id: string; // e.g. "issue-001"
  title: string;
  type: "AFK" | "human-in-the-loop";
  blockedBy: string[]; // ids of blocking issues
  closed: boolean;
}

const HARNESS = process.env.AGENT_CMD ?? "claude"; // "claude" or "opencode run"

async function loadIssues(dir: string): Promise<Issue[]> {
  const files = await readdir(dir);
  return Promise.all(
    files.map(async (f) => {
      const raw = await readFile(`${dir}/${f}`, "utf8");
      return parseIssue(f, raw); // omitted for brevity
    }),
  );
}

function unblocked(issues: Issue[]): Issue[] {
  const closed = new Set(issues.filter((i) => i.closed).map((i) => i.id));
  return issues.filter(
    (i) =>
      !i.closed && i.type === "AFK" && i.blockedBy.every((b) => closed.has(b)),
  );
}

function runInSandbox(issue: Issue): Promise<{ ok: boolean; branch: string }> {
  return new Promise((resolve) => {
    const branch = `afk/${issue.id}`;
    // 1. create a git worktree on a fresh branch
    // 2. start a docker container with that worktree mounted r/w
    // 3. run the harness inside, with the implement.md prompt
    const proc = spawn("scripts/run-sandbox.sh", [HARNESS, branch, issue.id], {
      stdio: "inherit",
    });
    proc.on("exit", (code) => resolve({ ok: code === 0, branch }));
  });
}

async function main() {
  let issues = await loadIssues("./issues");

  while (true) {
    const ready = unblocked(issues);
    if (ready.length === 0) {
      console.log("backlog drained or fully blocked - exiting");
      break;
    }

    // run all unblocked issues in parallel, one sandbox each
    const results = await Promise.all(ready.map(runInSandbox));

    // automated review on each successful branch BEFORE merge
    // (in a fresh session - smart-zone reviewer)
    for (const r of results.filter((r) => r.ok)) {
      await reviewBranch(r.branch);
    }

    // reload issues from disk; agents may have closed some and opened others
    issues = await loadIssues("./issues");
  }
}

async function reviewBranch(branch: string): Promise<void> {
  // spawn a *separate* agent session, smaller model, with the
  // diff and the coding-standards skill as input. Open a comment
  // on the PR. Do NOT auto-merge.
}

main();

Orchestrator में तीन principles embedded हैं और code से ज़्यादा matter करते हैं:

  1. Sandboxes mandatory हैं। Sandbox के बिना --permission-mode bypassPermissions के साथ AFK repositories destroy करने का तरीका है। हर slice को fresh container, fresh worktree, no production credentials, और सिर्फ़ ज़रूरत भर network egress मिलता है।
  2. Reviewer separate agent है। Implementer के same session में reviewer dumb zone में review कर रहा है। Fresh session में reviewer, जिसे सिर्फ़ diff और standards दिए गए हैं, work साफ़ देखता है। Smaller model review के लिए fine है (अक्सर अधिक critical); larger model implementation के लिए use करें।
  3. Loop हर iteration पर disk से issues reload करता है। जब QA §6.6 में नए issues generate करता है, वे queue में automatically दिखाई देते हैं।

6.5.3 Persistent loops और ambient agents​

ऊपर के loops backlog per once run होते हैं। वे start करते हैं, queue drain करते हैं, और stop करते हैं। Next evolution उन्हें running रखना है।

Boris Cherny के sense में loop agent invocation है जो cron से हर minute, हर पाँच minutes, या हर thirty minutes पर small standing job के against scheduled होता है। हर invocation fresh session है, इसलिए वह हर बार smart zone में start करता है और dumb-zone drift कभी accumulate नहीं करता। Agent alive नहीं रहता; job alive रहती है, और हर tick handle करने के लिए नया agent born होता है।

एक project पर working set of loops में ये शामिल हो सकते हैं:

  • PR janitor: flaky CI rerun करता है, main के against rebase करता है, reviewers के typo और lint comments fix करता है।
  • CI healer: जब flaky test intermittently fail होने लगे, investigate करके fix करता है।
  • Feedback clusterer: हर thirty minutes incoming user feedback pull करता है, उसे theme by group करता है, Slack पर summary post करता है।

ये tools नहीं हैं। ये ambient agents हैं: project के साथ चल रही persistent, low-intensity AI workforce, जो background tax handle करती है जिसने historically engineering hours खाए हैं, जैसे PR janitorial work, CI hygiene, ticket triage, dependency upkeep, log digestion, और monitoring summaries. कोई single task full AFK run justify नहीं करता; together वे real time consume करते हैं। उन्हें loops की तरह run करें और वे engineer के day से गायब हो जाते हैं।

Minimal persistent loop prompt file पर एक cron line है:

यहाँ क्या matter करता है। cron job command को schedule पर run करता है: मान लीजिए हर Tuesday 9am, या हर 30 minutes. पाँच characters */30 * * * * का मतलब है "हर 30 minutes, हर hour, हर day" (crontab.guru किसी भी schedule को decode करता है)। नीचे की line operating system को बताती है: "हर half hour, मेरे project folder में जाओ और PR-janitor agent को एक tick के लिए run करो." हर tick fresh agent session है जो जितना समय PRs को attention चाहिए उतना चलता है, फिर exit होता है। Job forever रहती है; agents disposable हैं।

# crontab -e
# every 30 minutes, run the PR-janitor agent in the project
*/30 * * * * cd /home/me/project && \
  AGENT_CMD="claude" ./scripts/run-once.sh prompts/pr-janitor.md
<!-- prompts/pr-janitor.md -->

You are the PR janitor for this project.

1. List my open PRs (`gh pr list --author @me`). # gh = GitHub's CLI
2. For each PR:
   - If CI failed on a known-flaky test, retrigger only that job.
   - If the PR has merge conflicts with main, attempt a clean rebase.
     If the rebase is non-trivial, leave a comment and stop.
   - If a reviewer left a typo / lint comment, fix it and push.
3. Commit only changes you can explain in one sentence.
4. Do nothing else. Output a one-line summary.

Heavier pattern routine है: same loop आपके laptop के cron के बजाय server-side execute हो, ताकि sleep, reboots, और travel survive करे। Coding-agent products में server-side scheduled-agent features emerge हो रहे हैं; local-cron version को development form और server-side version को production form treat करें। Prompt same है; scheduler ही बदलता है।

Persistent loops को दो design rules govern करते हैं:

  • हर tick fresh session है। Ticks के बीच कोई state survive नहीं करती, सिवाय environment में लिखी चीज़ों के (PRs, CI logs, छोटा status file)। Loop deliberately stateless है; prompt role carry करता है।
  • हर loop का एक job है। जो loop PR-janitor work और CI healing और feedback clustering करे, वह ऐसे session में degrade होगा जो इनमें से कोई भी अच्छी तरह नहीं करता। One loop per role, like one Skill per role.

AFK pattern अब end-to-end है: §6.5.1 one slice sequentially run करता है; §6.5.2 many slices parallel run करता है; §6.5.3 project द्वारा generate rhythms पर workforce indefinitely चलाता है। हर step team में किसी को add किए बिना throughput add करता है: Digital FTE workforce की operational shape.

6.6 Stage 6: Human review और QA​

Loop चलने के बाद सुबह आपके पास N pull requests हैं। Diffs पढ़ें, diffs की agent summary नहीं। Summary agent का word है कि उसने क्या किया; diff वह है जो उसने actually किया। दोनों subtle तरीकों से differ करते हैं जो सिर्फ़ production scale पर matter करते हैं।

Concrete example, §6.4 की gamification slice से। Agent की PR summary ने कहा: "Added points for lesson completion. Tests pass. Dashboard widget shows current total." Diff भी यही कहता था, सिवाय इसके कि QA pass ने पाया कि कोई lesson complete होने से पहले dashboard खोलने पर TypeError: Cannot read property 'awarded_at' of null से crash होता है। Agent ने service में empty-state handle किया था (0 को total_points से return करके) लेकिन React widget ने assume किया कि last_award_at timestamp exist करता है। One null check, easy fix; लेकिन agent's tests did not cover the empty-state UI render, क्योंकि slice की user story implicitly assume करती थी कि कम से कम एक award है। यह observation backlog में new issue के रूप में वापस जाता है ("add empty-state to dashboard widget; cover with a test") blocked by nothing, type AFK. PR merge होता है; night shift कल new issue pick करता है। यह loop, जहाँ human gap find करता है, ticket queue में वापस जाता है, और agent उसे AFK fix करता है, pipeline को self-improving बनाता है।

QA pipeline का सबसे valuable artifact produce करती है: new issues। हर bug found, हर UX concern, हर edge case जिसे original PRD ने miss किया, appropriate blocking relationships के साथ Kanban board पर नया ticket बनता है। Board कभी empty नहीं होता; वह slices produce करता रहता है।

यही वह stage है जहाँ taste रहती है। QA automate करने का temptation resist करने लायक है: agent जब agent की UI review करता है तो ऐसी opinion पर पहुँचता है जो किसी particular human की नहीं होती, और result वही gently-derivative, no-rough-edges slop होता है जो unsupervised AI output को characterize करता है। Human का "यह padding wrong है" और "यह label बहुत long है" decide करना irreducible step है। Agent normal pace के पाँच गुना ship करता है; आपका job यह ensure करना है कि वह पाँच गुना pace पर आपका taste ship करे, किसी और का नहीं।

7. AI-friendly codebases के architecture principles​

Workflow और codebase inseparable हैं: architecture जितनी साफ़ होगी, agent उसके अंदर उतना बेहतर perform करेगा। Architecture अब सिर्फ़ अपने आप में end नहीं; यह आपकी AI workforce का input है।

7.1 Deep modules, shallow modules से बेहतर​

Module deep होता है जब उसका interface छोटा और उसके पीछे बहुत behaviour हो; shallow जब interface और implementation roughly same size हों।

flowchart TB
    subgraph S["Shallow modules - bad"]
        direction LR
        s1[ ] ~~~ s2[ ] ~~~ s3[ ] ~~~ s4[ ] ~~~ s5[ ]
        s6[ ] ~~~ s7[ ] ~~~ s8[ ] ~~~ s9[ ] ~~~ s10[ ]
        SLABEL["many small pieces<br/>callers thread through<br/>implicit dependencies"]
    end

    subgraph D["Deep module - good"]
        direction TB
        DI["small interface<br/>━━━━━━━━━━━"]
        DBODY["large internal<br/>implementation<br/>(hidden from callers)"]
        DI --> DBODY
    end

    classDef bad fill:#fde8e8,stroke:#a83838,color:#5a0d0d
    classDef good fill:#e8f5e8,stroke:#3b8a3b,color:#0d3a0d
    classDef shallowCell fill:#f0d0d0,stroke:#a83838,color:#5a0d0d
    class S bad
    class D good
    class s1,s2,s3,s4,s5,s6,s7,s8,s9,s10 shallowCell

Agent के लिए difference decisive है। Shallow codebase में agent कई small files के बीच कई pairwise dependencies trace करता है; signal-to-noise per token degrade होता है; tests module boundaries के across sprawl करते हैं क्योंकि कोई single boundary isolation में test करने लायक enough behaviour contain नहीं करती। Deep codebase में agent एक interface पढ़ता है और boundary पर trust करता है। Tests interface पर बैठते हैं। Behaviour callers disturb किए बिना internally add हो सकता है, और उन्हें re-test किए बिना भी।

Difference concrete बनाने के लिए, GamificationService का shallow version कैसा दिखता, यह यहाँ है: वही तरीका जिसमें architectural guidance के बिना agent same feature लिखता है।

यहाँ क्या matter करता है। हर block में exported items की संख्या count करें। Shallow version नौ top-level functions expose करता है जिन्हें callers को right order और combination में call करना याद रखना होता है। Deep version single class पर तीन methods expose करता है; behind the scenes जो होना है, behind the scenes होता है। Avoid करने वाला bug: shallow version में caller validateAntiCheat invoke करना भूल सकता है और silently system corrupt कर सकता है। Deep version में caller validateAntiCheat तक पहुँच ही नहीं सकता; वह awardLessonCompletion के अंदर hidden है, जो उसे automatically call करता है। Right things hide करना deep module का पूरा job है।

// gamification/index.ts - SHALLOW: the interface IS the implementation
export function awardPoints(studentId: string, reason: string, n: number): void;
export function totalPoints(studentId: string): number;
export function recordStreakActivity(studentId: string, day: Date): void;
export function streakLength(studentId: string, today: Date): number;
export function computeLevel(totalPoints: number): number;
export function validateAntiCheat(
  studentId: string,
  event: PointEvent,
): boolean;
export function backfillHistorical(studentId: string, since: Date): void;
export function pointsForLessonCompletion(): number;
export function pointsForQuizPass(): number;
// ... + the data classes each function depends on

नौ top-level functions, हर एक कहीं से भी callable, हर एक silently दूसरों पर dependent (awardPoints को validateAntiCheat call करना चाहिए; dashboard को one lesson completion के लिए awardPoints और recordStreakActivity और computeLevel call करना चाहिए; अगर कोई caller एक भूल जाए, system silently consistency से drift करता है)।

§6.4 के deep version से compare करें:

// gamification/service.ts - DEEP: small interface, large hidden body
export class GamificationService {
  awardLessonCompletion(studentId: string): PointAward; // does ALL of the above internally
  totalPoints(studentId: string): number;
  currentStreak(studentId: string): number;
  // streak recording, anti-cheat, level calc, point amounts → all hidden
}

तीन methods. Internally same नौ concerns exist करते हैं, लेकिन वे interface नहीं हैं। Callers validateAntiCheat call करना नहीं भूल सकते, क्योंकि callers उसे call कर ही नहीं सकते। Tests तीन methods पर बैठते हैं, नौ पर नहीं। New behaviour (recordStreak, level threshold, backfill) contract बदले बिना अंदर add होता है: exactly वह property जिसे §6.4 demonstrate करता है।

Heuristic. अगर आपके IDE की Outline view किसी module के public interface से लंबी है, module shallow है। उसे deepen करें।

7.2 Interface पर test करें​

§7.1 का corollary. Tests module interfaces पर बैठते हैं, internal functions पर नहीं। Internal function पर test implementation को pin करता है; internals refactor करने पर test break होता है, भले externally visible behaviour correct हो। Interface पर test behaviour pin करता है; internals freely बदलते हैं जब तक contract hold करे।

tdd Skill default में यही enforce करता है: tests interface target करते हैं; agent green steps के बीच internals refactor करता है; suite small surface area से full coverage देती है।

7.3 Interface design करें, implementation delegate करें​

Agents के साथ काम कर रहे senior engineer के लिए सबसे important habit.

आप decide करते हैं module क्या expose करता है: contract, names, invariants. ये decisions हर caller को affect करते हैं; architecture shape करते हैं; taste और whole system mind में require करते हैं।

Agent decide करता है contract कैसे satisfy होगा: internal data structures, helper placement, order of operations. ये सिर्फ़ एक module के अंदर affect करते हैं; mistakes recoverable हैं; architectural map की ज़रूरत नहीं।

यह gray box principle है। Outside से module fully specified है: interface visible, internals invisible-by-design. Inside से agent excellent work करने के लिए free है, सिर्फ़ interface contract से constrained. Senior engineer million-line codebase का architectural map head में hold कर सकता है क्योंकि map में सिर्फ़ interfaces होते हैं।

यही Failure 5 के brain-saturation problem को tractable बनाता है। आप agent की लिखी हर line नहीं पढ़ सकते; वह road burnout की तरफ़ जाती है। आप module map head में रख सकते हैं और हर interface change carefully पढ़ सकते हैं। Interfaces पर change-set छोटा है; modules के अंदर change-set बड़ा है। Small set पर attention concentrate करना ही scale करता है।

7.4 improve-codebase-architecture Skill​

Codebases समय के साथ shallow की तरफ़ drift करते हैं, especially जब उनमें agents हों। Fix periodic deepening pass है।

Karpathy भी, latest models के साथ frontier पर काम करते हुए, experience plainly describe करते हैं: "Sometimes I get a little bit of a heart attack because the code is very bloaty and there's a lot of copy paste, and awkward abstractions that are brittle. It works, but it's just really gross." यह deep model failing नहीं है; यह model "does the code run" वाले verifiable circuit के अंदर perform कर रहा है, बिना "is the code well-designed" के corresponding reward के। Deepening pass वह reward supply करता है जो labs ने नहीं दिया।

---
name: improve-codebase-architecture
description: Find shallow-module candidates in the codebase and propose deepenings. Run weekly, or after a burst of feature work.
---

You are an architecture reviewer. Walk the codebase and find places
where understanding one concept requires bouncing between many small
files; where pure functions have been extracted only for testability,
not behaviour; where modules are tightly coupled at the seams.

Surface a numbered list of deepening candidates. For each, briefly:

- which existing files would collapse into the new deep module
- what the new interface would be (3-5 method signatures, no more)
- what behaviour would move inside, freeing callers from knowing it

Do NOT make changes. Open a markdown RFC describing the highest-value
candidate as an issue, blocked by nothing, type AFK.

Weekly run एक deepening RFC produce करता है। वह same Kanban board में enter करता है जिससे feature work flow करता है। उसे same TDD-on-vertical-slices loop से implement किया जाता है। Codebase accident से नहीं, schedule पर healthier होता है।

8. Working vocabulary​

Precise vocabulary reasoning speed up करती है। Full reference Dictionary of AI Coding है; नीचे का subset इस book का बाकी हिस्सा पढ़ने और लिखने के लिए minimum है।

TermMeaning
ModelParameters. Stateless. Next-token prediction करता है; और कुछ नहीं।
HarnessModel के आसपास की हर चीज़ जो उसे agent बनाती है: tools, system prompt, context-window management, permissions. Claude Code harness है; OpenCode harness है.
AgentModel + harness जो context window में tools के साथ operate करता है। जिससे आप actually बात करते हैं।
Context windowFixed-size byte view जिसे model हर request पर देखता है। Finite. यही एक surface है जिसके through model कुछ भी perceive करता है।
Smart zone / dumb zoneEarly-session region जहाँ attention sharp है / late-session region जहाँ competing tokens से attention diluted है।
HallucinationConfidently-wrong output. Factuality hallucinations parametric knowledge के gaps से आती हैं; faithfulness hallucinations dumb zone में drift से। Fixes अलग हैं।
ClearingSession end करके fresh one start करना। Hard reset. Agent को known state में लौटाता है।
CompactionSession को in-memory summarise करके new one seed करना। Lossy; कुछ dumb-zone reasoning preserve करता है।
HandoffArtifact (PRD, ticket, CONTEXT.md) के through context को एक session से दूसरे में transfer करना।
AFK"Away from keyboard." User session kick off करता है और उसे sandbox में unattended run करने देता है।
SkillTeachable capability जो SKILL.md file के रूप में bundled है। On demand load होती है। Progressive disclosure की unit.
Tracer bullet / vertical sliceIssue जो system की हर layer से होकर thin path end-to-end ship करता है।
Deep moduleSmall interface और large internal implementation वाला module. AI codebases को scalable बनाने वाली shape.
Design conceptजो build किया जा रहा है उसका shared, ephemeral idea, user और agent के बीच common held. Asset नहीं।
GrillingDesign concept form करने की technique: agent user को Socratically interview करता है, one decision at a time.
Vibe codingHuman review के बिना agent code accept करना। "Low-quality coding" से distinct; term output नहीं, review stance name करती है।
Agentic engineeringProduction work में agents इस्तेमाल करने की discipline while preserving the quality bar of professional software. Vibe coding के opposite stance: floor raised, ceiling held.
Jagged intelligenceEmpirical fact कि LLM capability उन tasks पर sharply peak करती है जिनके लिए labs ने verifiable RL से train किया (math, code), और उन circuits के बाहर stagnate करती है। 100k lines refactor करने वाला agent आपको 50 m दूर car wash तक walk करने को भी कह सकता है।
On distributionModel के training data में well-represented होने और इसलिए competently handle होने की property. Fresh start करते समय वह stacks चुनें जिनमें model already strong है।
Loop / RoutinePersistent ambient agent: small standing job के against schedule पर invoked fresh session (locally cron; server-side "routine"). हर tick stateless; role prompt में persist करता है।

Working coder को इनमें से कोई भी term बिना hesitation use करना चाहिए। "मैं clear करूँगा, फिर next unblocked vertical slice पर tdd run करूँगा" और "यह faithfulness hallucination है; docs अब भी context में हैं, इसने बस turn forty के आसपास उन्हें पढ़ना बंद कर दिया" ऐसी sentences हैं जो vague conversation को actual work वाली conversation से अलग करती हैं।

9. Practical drills​

तीन exercises. Order में करें। हर एक thirty minutes से two hours लेता है।

Drill 1: grill-me install करें और real idea पर run करें। कोई feature pick करें जिसे आप scope करने से टाल रहे हैं। §5.2 follow करके clean repo में skill pack install करें (Claude Code readers: पहले mkdir -p .claude/skills, फिर npx skills@latest add mattpocock/skills)। Claude Code (या OpenCode) खोलें, /grill-me invoke करें, और questions answer करें जब तक agent stop न करे। Shortcut न लें। Questions count करें। Note करें कौन से decisions आप अपने दम पर surface नहीं करते।

"Good" कैसा दिखता है। Non-trivial feature पर grilling session अक्सर 15-40 questions और 30-90 minutes तक चलता है, फिर agent alignment report करता है। Roughly 10 questions से कम का मतलब आम तौर पर idea बहुत छोटा था या आपने बहुत generously answer किया; 60 से ऊपर का मतलब अक्सर agent fishing कर रहा है, इसलिए interrupt करें और हर question पर recommendation commit करने को कहें। End तक आप कम से कम तीन ऐसे decisions paraphrase कर पाएँ जिन्हें आपने पहले consider नहीं किया था। अगर नहीं, तो वह grilling नहीं, survey था। Useful diagnostic ratio: roughly हर पाँच questions में एक ऐसा decision surface करे जिसे आपने पहले resolve नहीं किया था।

Drill 2: Vertical slice को tracer bullet की तरह लिखें। अपने codebase में कोई unfinished feature लें। Smallest possible end-to-end path trace करने वाली single user story लिखें। उसे tdd Skill के under implement करें। Notice करें slice कितना short है। Notice करें integration bugs horizontal slicing की तुलना में कितनी जल्दी surface होते हैं।

"Good" कैसा दिखता है। Slice under one session land होती है, test, implementation, और reviewable diff एक PR में। अगर नहीं, slice बहुत thick थी; split करें। Slice के during जो integration friction आता है वही drill का value है; उसे new issues के रूप में capture करें, current slice को absorb करने के लिए expand न करें।

Drill 3: Module deepen करें। जिस codebase को आप अच्छी तरह जानते हैं उस पर improve-codebase-architecture run करें। Highest-value candidate pick करें। अभी implement न करें; paper पर new interface sketch करें (3-5 method signatures, no more)। New interface के surface area को old one से compare करें (उन files के public symbols का sum जो collapse होंगी)। Ratio आपका concrete measure है कि codebase कितना shallow हो गया था।

"Good" कैसा दिखता है। Genuine deepening आम तौर पर several small modules (लगभग 5 से 15) को एक deep module में collapse करती है, public-symbol ratio (old : new) लगभग 3:1 या higher। अगर ratio 1:1 के करीब है, candidate actually shallow नहीं था; दूसरा चुनें।

Daily work के लिए short checklist:

  • क्या मैंने आज का session start करने से पहले /clear किया?
  • क्या मैंने किसी non-trivial change के लिए grill-me इस्तेमाल किया?
  • क्या मेरे issues vertical slices हैं, horizontal phases नहीं?
  • क्या हर implementation slice tdd से run हो रही है?
  • क्या AFK runs sandbox में हैं?
  • क्या reviewer implementer से separate session है?
  • क्या मैंने summary नहीं, diff पढ़ा?

10. Closing: strategic programmer​

ले जाने वाली picture यह है।

आपका agent excellent tactical programmer है: ground पर sergeant जो किसी भी well-specified hill को, किसी भी language में, किसी भी framework में, रात के बीच में ले सकता है और सुबह तक working slice वापस ला सकता है। आपको उसे function या test लिखना सिखाने की ज़रूरत नहीं। Harness, model, और tools ने वह solve कर दिया है।

जो sergeant नहीं कर सकता, वह है decide करना कौन सा hill। वह आपको नहीं बता सकता कि बन रहा system business को चाहिए वही system है या नहीं। वह नहीं बता सकता कि तीसरा module जिसे आप माँगने वाले हैं, separate module exist करना चाहिए या existing deep one में fold होना चाहिए। वह नहीं बता सकता कि जो code आपने माँगा है वह domain constraint violate करता है जो कहीं लिखा ही नहीं गया। वह months और years तक system का architectural map mind में नहीं रख सकता; उसके पास months और years नहीं हैं; उसके पास current session और disk पर कुछ files हैं।

Sergeant के ऊपर की हर चीज़ strategic programmer का role है, जो आपका role है। Stakeholder के साथ align करना। Design concept form करना। Slice चुनना। Interface design करना। Diff पढ़ना। Map hold करना। हर दिन system के design में invest करना, जैसा Kent Beck ने humans के लिए तीस साल पहले लिखा था, और जो अब human engineers और Digital FTEs की hybrid workforce पर apply होता है जो अगले decade का software बनाएगी।

Strategic programmer के tools इस chapter में describe हैं। Pipeline (§4). छह failures (§3) और उनके cures. Skills (§5) जो cures encode करती हैं। Architecture (§7) जो agent को अच्छा बनाती है। Vocabulary (§8) जिससे आप इन सब पर reason कर सकते हैं। Claude Code और OpenCode में discipline same है। Python और TypeScript में discipline same है। आज से पाँच साल बाद जो भी model और harness exist करे, discipline तब भी same रहेगी।

इस chapter की शुरुआत वाला narrative, कि AI software fundamentals replace करता है, wrong है क्योंकि वह code कौन लिख रहा है को good code कैसा दिखता है से confuse करता है। Author बदल गया; standard नहीं। जो codebases humans के लिए अच्छे थे, agents के लिए अच्छे हैं। जो codebases humans के लिए खराब थे, agents के लिए खराब हैं, और worse, क्योंकि agents badness amplify करते हैं।

पुरानी books पढ़ें। The Pragmatic Programmer. A Philosophy of Software Design. Domain-Driven Design. Extreme Programming Explained. The Design of Design. हर page इस technology से पहले का है, और हर page अब पहले से ज़्यादा sharply apply होता है। यही वह तरीका है जिससे strategic programmer उन timescales पर सोचना सीखता है जहाँ sergeant नहीं पहुँच सकता।

Karpathy की एक line साथ ले जाने लायक है: "You can outsource your thinking, but you can't outsource your understanding." Agent typing, searching, boilerplate, API-detail recall, tedious refactor करेगा। Increasingly वह thinking भी करेगा: options generate करना, weigh करना, solutions draft करना, experiments run करना। जो uniquely आपका रहता है वह understanding है, कि यह system क्यों बन रहा है, किसलिए है, कौन इस पर rely करता है, इसे क्या कभी नहीं करना चाहिए। Understanding ही आपको agent direct करने देती है। इसके बिना agent के पास destination नहीं, और destination के बिना fast agent सिर्फ़ खो जाने का expensive तरीका है।

Corollary, Boris Cherny से: जब coding solved हो और domain knowledge bottleneck हो, software लिखने के लिए best person वह है जो domain को best समझता है, वह नहीं जिसने historically software लिखा है। Accounting software का best author बहुत अच्छा accountant है। Historical analogy printing press है: Gutenberg से पहले reading specialist trade थी जिसे small literate minority practice करती थी; उनकी press के decades के अंदर printed output explode हुआ; following centuries में literacy broad majority skill बन गई और profession रहना बंद हो गई। Same arc अब software के लिए शुरू हो रही है। एक generation में, software बनाना हर domain के professionals का matter-of-course काम होगा (accountants जो अपनी ledgers लिखते हैं, doctors जो अपने clinical workflows लिखते हैं, lawyers जो अपने contract analysers लिखते हैं, teachers जो अपने curriculum tools लिखते हैं) और जिस role को हम "engineer" कहते हैं उसका मतलब narrower और deeper होगा: वह person जो substrate design करता है जिस पर बाकी workforce build करती है।

यह वही workforce shape है जिसके बारे में यह book है। अगले chapters में आप जो Digital FTE manufacture करेंगे वह domain expert का tool है: agentic engineer द्वारा built, लेकिन accountant, underwriter, analyst, case manager द्वारा specified, governed, और used, जो work own करता है। इस chapter के principles और workflows उन Digital FTEs को इतना trustworthy बनाते हैं कि वे उस ownership के deserving हों। Pipeline, Skills, deep modules, persistent loops, sandboxes, smart-zone discipline, jagged-intelligence awareness: सब software की service में जिसे domain expert code की एक line पढ़े बिना rely कर सके। यही agentic engineering का contract है उन लोगों के साथ जिन्हें वह serve करती है।

काम यही है। Chapter यही है।

Further reading​

  • Matt Pocock, Software Fundamentals Matter More Than Ever: keynote जो इस chapter की thesis inform करती है।
  • Matt Pocock, Full Walkthrough: Workflow for AI Coding: §4 और §5 की pipeline का two-hour live walkthrough.
  • Matt Pocock, 5 Claude Code Skills I Use Every Single Day: daily-Skills reference.
  • Matt Pocock, Dictionary of AI Coding: canonical glossary; §8 का source.
  • Matt Pocock, Skills for Real Engineers: पूरे chapter में इस्तेमाल किया गया installable skill pack.
  • Andrej Karpathy, From Vibe Coding to Agentic Engineering: वह talk जो discipline को name करती है, Software 1.0/2.0/3.0 framing articulate करती है, और jagged intelligence तथा animals vs. ghosts lens introduce करती है जो §1 और §2 में use हुआ।
  • Boris Cherny (Anthropic), Why Coding Is Solved, and What Comes Next: Claude Code के creator, अपने personal workflow, stack choice के लिए "on-distribution" argument, persistent loops और routines, और printing-press analogy पर, जिसका use §1.2, §2.3, §6.5.3, और §10 में हुआ।
  • John Ousterhout, A Philosophy of Software Design: deep modules, shallow modules.
  • David Thomas & Andrew Hunt, The Pragmatic Programmer: tracer bullets, headlights.
  • Eric Evans, Domain-Driven Design: ubiquitous language.
  • Kent Beck, Extreme Programming Explained: हर दिन design में invest करें।
  • Frederick P. Brooks, The Design of Design: design tree, design concept.

Companion Skills (यह chapter)​

Chapter की pipeline Matt Pocock के pack के छह Skills से चलती है, direct reading के लिए सभी यहाँ linked हैं:

  • grill-me: Socratic interview जो design concept produce करता है।
  • grill-with-docs: grilling जो साथ-साथ CONTEXT.md और ADRs inline लिखता है (§3 Failure 2 से "ubiquitous language" lineage).
  • to-prd: conversation को PRD में synthesise करें।
  • to-issues: PRD को tracer-bullet tickets में split करें।
  • tdd: red-green-refactor, एक slice at a time.
  • improve-codebase-architecture: shallow modules खोजें, deepenings propose करें, RFC open करें।

One-time bootstrap, setup-matt-pocock-skills, per repo पहले run होता है और issue-tracker config तथा docs/agents/ layout scaffold करता है जिन पर engineering skills depend करते हैं।

Matt का pack total fourteen skills ship करता है (full repo). Seven-stage pipeline और setup-matt-pocock-skills से आगे, इसमें diagnose (disciplined bug debugging), triage (state-machine ticket triage), zoom-out (broader-context reframing), prototype (throwaway design prototypes), write-a-skill (new skills बनाने के लिए meta-Skill), handoff (§4.1 की session-to-session handoff artifact discipline), और caveman (terse-prompt mode) भी शामिल हैं। वे seven-stage pipeline के बाहर बैठते हैं लेकिन उसके साथ compose करते हैं, और हर एक Claude Code और OpenCode में identically चलता है। Agent Factory Skillpack reference और additional book-specific Skills के लिए Part 5: Building OpenClaw Apps देखें।