-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathagentic-guide.html
More file actions
3013 lines (2810 loc) · 197 KB
/
Copy pathagentic-guide.html
File metadata and controls
3013 lines (2810 loc) · 197 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en">
<head>
<script async src="https://www.googletagmanager.com/gtag/js?id=G-62YF7Y81BS"></script>
<script>window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}gtag('js',new Date());gtag('config','G-62YF7Y81BS');</script>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>The Agentic Engineering Guide</title>
<meta name="description" content="33 chapters on AI agent infrastructure. Context engineering, security, orchestration, production ops.">
<link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,300;1,9..40,400&family=DM+Serif+Display:ital@0;1&family=DM+Mono:wght@300;400;500&display=swap" rel="stylesheet">
<style>
/* ── DESIGN SYSTEM: Dieter Rams · Howard Marks ── */
:root{
--paper:#ffffff;
--bg:#f7f6f2;
--ink:#111111;
--mid:#555555;
--muted:#999999;
--rule:#dedbd3;
--light:#f0ede6;
--red:#c0392b; /* single accent — Braun red */
--mono:'DM Mono',monospace;
}
*{box-sizing:border-box;margin:0;padding:0;}
html{scroll-behavior:smooth;}
body{
font-family:'DM Sans',sans-serif;
font-weight:400;
background:var(--bg);
color:var(--ink);
max-width:820px;
margin:0 auto;
padding:0 0 100px;
line-height:1.75;
font-size:15px;
letter-spacing:-.01em;
-webkit-font-smoothing:antialiased;
}
/* ── MASTHEAD ── */
.masthead{
border-bottom:1px solid var(--ink);
padding:48px 36px 36px;
background:var(--paper);
position:relative;
overflow:hidden;
}
.masthead::after{
content:'';
position:absolute;
bottom:0;left:0;right:0;
height:3px;
background:var(--red);
}
.back-link{
display:inline-flex;align-items:center;gap:6px;
font-family:var(--mono);font-size:10px;letter-spacing:.12em;
text-transform:uppercase;color:var(--muted);
text-decoration:none;margin-bottom:32px;
transition:color .2s;
}
.back-link:hover{color:var(--ink);}
.mast-label{
font-family:var(--mono);font-size:10px;letter-spacing:.18em;
text-transform:uppercase;color:var(--muted);margin-bottom:10px;
}
.mast-title{
font-family:'DM Serif Display',serif;
font-size:48px;font-weight:400;line-height:1.05;
letter-spacing:-.025em;margin-bottom:16px;
}
.mast-title em{font-style:italic;font-weight:400;}
.mast-rule{height:1px;background:var(--rule);margin:20px 0 16px;}
.mast-sub{font-size:13px;color:var(--mid);display:flex;gap:24px;flex-wrap:wrap;}
.mast-sub span{display:flex;align-items:center;gap:6px;}
.mast-sub span::before{content:'—';color:var(--red);}
/* ── ANIMATED RULE (the Braun red line) ── */
@keyframes extend-rule{from{transform:scaleX(0);}to{transform:scaleX(1);}}
.animated-rule{
height:3px;background:var(--red);
transform-origin:left;
animation:extend-rule .8s cubic-bezier(.16,1,.3,1) forwards;
}
/* ── PAGE BODY ── */
.page-body{padding:0 36px;}
@media(max-width:600px){
.masthead{padding:36px 20px 28px;}
.mast-title{font-size:32px;}
.page-body{padding:0 20px;}
}
/* ── TOC ── */
.toc-wrap{margin:32px 0 0;}
.toc-btn{
display:flex;justify-content:space-between;align-items:center;
background:var(--paper);border:1px solid var(--rule);
padding:13px 18px;cursor:pointer;
font-family:var(--mono);font-size:11px;letter-spacing:.1em;
text-transform:uppercase;color:var(--mid);
user-select:none;transition:border-color .2s;width:100%;
}
.toc-btn:hover{border-color:var(--ink);color:var(--ink);}
.toc-body{
display:none;border:1px solid var(--rule);border-top:none;
background:var(--paper);padding:20px 24px;
}
.toc-body.open{display:grid;grid-template-columns:repeat(auto-fill,minmax(240px,1fr));gap:20px;}
.toc-part-name{
font-family:var(--mono);font-size:9px;text-transform:uppercase;
letter-spacing:.16em;color:var(--red);font-weight:500;
margin-bottom:8px;padding-bottom:5px;border-bottom:1px solid var(--rule);
}
.toc-part ol{list-style:none;}
.toc-part ol li{margin-bottom:4px;}
.toc-part ol li a{
font-size:12px;color:var(--ink);text-decoration:none;
transition:color .15s;display:block;padding:1px 0;
font-family:'Inter',sans-serif;
}
.toc-part ol li a:hover{color:var(--red);}
/* ── PART HEADER ── */
.part-header{margin:64px 0 20px;padding-top:20px;border-top:2px solid var(--ink);}
.part-num-badge{
font-family:var(--mono);font-size:9px;text-transform:uppercase;
letter-spacing:.18em;color:var(--muted);margin-bottom:8px;
}
.part-title{
font-family:'DM Serif Display',serif;font-size:28px;font-weight:400;
margin-bottom:6px;letter-spacing:-.015em;
}
.part-desc{font-size:13px;color:var(--mid);max-width:560px;line-height:1.6;}
/* ── CHAPTER ACCORDION ── */
details.chapter{
background:var(--paper);border:1px solid var(--rule);
margin-bottom:8px;overflow:hidden;transition:border-color .2s;
}
details.chapter[open]{border-color:var(--ink);}
summary.chapter-summary{
display:flex;align-items:center;gap:14px;
padding:15px 20px;cursor:pointer;list-style:none;
transition:background .15s;user-select:none;
}
summary.chapter-summary::-webkit-details-marker{display:none;}
summary.chapter-summary:hover{background:var(--bg);}
details.chapter[open] summary.chapter-summary{background:var(--bg);}
.ch-num{
font-family:var(--mono);font-size:9px;text-transform:uppercase;
letter-spacing:.15em;color:var(--muted);white-space:nowrap;
min-width:56px;
}
.ch-info{flex:1;}
.ch-title{font-size:14px;font-weight:600;color:var(--ink);letter-spacing:-.01em;}
.ch-tldr{font-size:12px;color:var(--muted);margin-top:2px;display:none;line-height:1.5;}
details.chapter[open] .ch-tldr{display:block;}
.ch-arrow{
font-size:18px;color:var(--muted);transition:transform .25s;
flex-shrink:0;font-family:var(--mono);font-weight:300;
}
details.chapter[open] .ch-arrow{transform:rotate(45deg);color:var(--red);}
/* ── CHAPTER BODY ── */
.chapter-body{padding:0 24px 28px;border-top:1px solid var(--rule);}
.chapter-body h2{
font-family:'DM Serif Display',serif;font-size:20px;font-weight:400;
margin:28px 0 10px;letter-spacing:-.01em;
}
.chapter-body h2:first-child{margin-top:24px;}
.chapter-body h3{
font-size:10px;font-weight:600;margin:22px 0 8px;
text-transform:uppercase;letter-spacing:.14em;color:var(--muted);
}
.chapter-body p{margin-bottom:14px;color:#2a2a2a;}
.chapter-body p:last-child{margin-bottom:0;}
.chapter-body ul,.chapter-body ol{margin:10px 0 16px 18px;}
.chapter-body li{margin-bottom:6px;color:#2a2a2a;}
.chapter-body blockquote{
border-left:2px solid var(--red);margin:20px 0;
padding:10px 0 10px 18px;font-style:italic;color:var(--mid);
font-family:'DM Serif Display',serif;font-size:16px;line-height:1.7;
}
.chapter-body table{
width:100%;border-collapse:collapse;margin:16px 0;
font-size:12px;overflow-x:auto;display:block;
}
.chapter-body th{
background:var(--bg);font-weight:600;text-align:left;
padding:8px 12px;border:1px solid var(--rule);
font-family:var(--mono);font-size:9px;letter-spacing:.1em;
text-transform:uppercase;color:var(--muted);
}
.chapter-body td{padding:8px 12px;border:1px solid var(--rule);vertical-align:top;}
.chapter-body tr:nth-child(even) td{background:var(--bg);}
.chapter-body code{
font-family:var(--mono);font-size:11px;background:var(--light);
padding:2px 5px;color:var(--red);
}
.chapter-body pre{
background:#111;color:#eee;padding:18px 20px;
font-family:var(--mono);font-size:11px;
overflow-x:auto;margin:14px 0;line-height:1.6;
}
.chapter-body a{color:var(--red);}
/* ── TL;DR (Howard Marks memo style) ── */
.tldr{
border-left:2px solid var(--ink);margin:4px 0 22px;
padding:10px 0 10px 16px;
}
.tldr strong{
font-family:var(--mono);font-size:9px;text-transform:uppercase;
letter-spacing:.16em;color:var(--muted);display:block;margin-bottom:5px;
}
.tldr span{font-size:13px;color:var(--mid);line-height:1.7;}
/* ── ANALOGY ── */
.analogy{
background:var(--bg);border:1px solid var(--rule);
padding:14px 16px;margin:18px 0;
}
.analogy strong{
font-family:var(--mono);font-size:9px;text-transform:uppercase;
letter-spacing:.14em;color:var(--muted);display:block;margin-bottom:5px;
}
.analogy span{font-size:13px;color:var(--mid);line-height:1.65;}
/* ── STAT GRID ── */
.stat-grid{
display:grid;grid-template-columns:repeat(auto-fit,minmax(130px,1fr));
gap:1px;margin:20px 0;background:var(--rule);border:1px solid var(--rule);
}
.stat-card{
background:var(--paper);padding:18px 16px;
}
.stat-val{
font-family:'DM Serif Display',serif;font-size:30px;font-weight:400;
color:var(--ink);line-height:1;margin-bottom:6px;
}
.stat-val.red{color:var(--red);}
.stat-label{font-size:11px;color:var(--muted);line-height:1.4;}
/* ── DIAGRAM ── */
.diagram{
margin:22px 0;padding:24px 20px 16px;
background:var(--paper);border:1px solid var(--rule);
overflow-x:auto;text-align:center;
}
.diagram svg{display:block;margin:0 auto;max-width:100%;}
.diagram figcaption{
font-family:var(--mono);font-size:10px;color:var(--muted);
text-align:left;margin-top:14px;letter-spacing:.05em;
border-top:1px solid var(--rule);padding-top:10px;
}
/* ── CONCEPT ROW ── */
.concept-row{display:flex;gap:1px;margin:20px 0;background:var(--rule);}
.concept-card{
flex:1;min-width:100px;background:var(--paper);
padding:16px 14px;transition:background .15s;
}
.concept-card:hover{background:var(--bg);}
.cc-num{
font-family:var(--mono);font-size:20px;font-weight:700;
color:var(--red);line-height:1;margin-bottom:8px;
}
.cc-title{font-size:13px;font-weight:600;color:var(--ink);margin-bottom:4px;}
.cc-desc{font-size:11px;color:var(--muted);line-height:1.5;}
/* ── LEVEL STRIP ── */
.level-strip{display:flex;gap:1px;margin:20px 0;background:var(--rule);}
.level-item{flex:1;background:var(--paper);padding:14px 10px;text-align:center;}
.level-num{font-family:var(--mono);font-size:16px;font-weight:700;color:var(--ink);margin-bottom:3px;}
.level-name{font-size:11px;font-weight:600;color:var(--ink);margin-bottom:3px;}
.level-desc{font-size:10px;color:var(--muted);line-height:1.3;}
/* ── COMPARE ── */
.compare{display:grid;grid-template-columns:1fr 1fr;gap:1px;margin:20px 0;background:var(--rule);}
.compare-panel{background:var(--paper);padding:16px;}
.compare-panel h4{font-size:12px;font-weight:700;margin-bottom:10px;letter-spacing:.02em;}
.compare-panel ul{list-style:none;padding:0;}
.compare-panel ul li{font-size:12px;color:var(--mid);padding:4px 0;border-bottom:1px solid var(--rule);}
.compare-panel ul li:last-child{border-bottom:none;}
.compare-panel ul li::before{content:'— ';color:var(--red);}
@media(max-width:480px){.compare{grid-template-columns:1fr;}}
/* ── STEP FLOW ── */
.step-flow{display:flex;gap:0;margin:20px 0;background:var(--rule);gap:1px;}
.step-item{flex:1;min-width:80px;background:var(--paper);padding:14px 12px;text-align:center;}
.s-num{font-family:var(--mono);font-size:9px;text-transform:uppercase;letter-spacing:.12em;color:var(--red);margin-bottom:4px;}
.s-name{font-size:12px;font-weight:600;color:var(--ink);margin-bottom:3px;}
.s-desc{font-size:10px;color:var(--muted);line-height:1.4;}
.step-arrow{display:none;}
@media(max-width:500px){.step-flow{flex-direction:column;}}
/* ── PILL LIST ── */
.pill-list{display:flex;flex-wrap:wrap;gap:6px;margin:14px 0;}
.pill{
background:var(--bg);border:1px solid var(--rule);
padding:5px 12px;font-size:11px;color:var(--mid);
font-family:var(--mono);letter-spacing:.04em;
}
/* ── INSIGHT / DANGER ── */
.insight,.danger{padding:12px 16px;margin:16px 0;font-size:13px;}
.insight{border-left:2px solid var(--ink);background:var(--bg);}
.insight p,.danger p{margin:0;color:var(--mid);}
.danger{border-left:2px solid var(--red);background:var(--bg);}
.danger p{color:#7a1a1a;}
/* ── ANIMATED DIAGRAMS ── */
/* Agent loop dot */
@keyframes orbit{
0%{offset-distance:0%;}
100%{offset-distance:100%;}
}
.orbit-dot{
offset-path:path('M 60 130 C 60 80 130 40 200 40 C 270 40 340 80 340 130 C 340 180 270 220 200 220 C 130 220 60 180 60 130 Z');
offset-distance:0%;
animation:orbit 3s linear infinite;
position:absolute;
width:8px;height:8px;
background:var(--red);
border-radius:50%;
margin-left:-4px;margin-top:-4px;
}
/* Draw-on animation for SVG paths */
@keyframes draw{from{stroke-dashoffset:var(--path-len,1000);}to{stroke-dashoffset:0;}}
.draw-on{
stroke-dasharray:var(--path-len,1000);
stroke-dashoffset:var(--path-len,1000);
}
details.chapter[open] .draw-on{
animation:draw 1.2s cubic-bezier(.4,0,.2,1) forwards .1s;
}
/* Bar fill animation */
@keyframes fill-bar{from{transform:scaleX(0);}to{transform:scaleX(1);}}
.fill-bar{transform-origin:left;transform:scaleX(0);}
details.chapter[open] .fill-bar{animation:fill-bar .8s cubic-bezier(.4,0,.2,1) forwards .2s;}
/* Dot pulse */
@keyframes pulse{0%,100%{opacity:1;r:4;}50%{opacity:.5;r:6;}}
/* ── FOOTER ── */
.page-footer{
margin:0 36px;padding:20px 0;border-top:1px solid var(--rule);
font-family:var(--mono);font-size:10px;color:var(--muted);
display:flex;justify-content:space-between;letter-spacing:.06em;
}
@media(max-width:600px){.page-footer{margin:0 20px;}}
</style>
</head>
<body>
<div class="masthead">
<a href="index.html" class="back-link">← Index</a>
<div class="mast-label">AI  /  ML</div>
<h1 class="mast-title">The Agentic<br><em>Engineering Guide</em></h1>
<div class="mast-rule"></div>
<div class="mast-sub">
<span>10 Parts</span>
<span>33 Chapters</span>
<span>Diagrams & Animations</span>
<span>No Jargon</span>
</div>
</div>
<div class="page-body">
<div class="toc-wrap">
<button class="toc-btn" id="toc-toggle">
<span>Contents — All 33 Chapters</span>
<span>+</span>
</button>
<div class="toc-body" id="toc-body">
<div class="toc-part"><div class="toc-part-name">Part 1 · Foundations</div><ol>
<li><a href="#ch01">01 — The Agentic Landscape</a></li>
<li><a href="#ch02">02 — The Capability Jump</a></li>
<li><a href="#ch03">03 — The AAIF Standards</a></li>
</ol></div>
<div class="toc-part"><div class="toc-part-name">Part 2 · Context Engineering</div><ol>
<li><a href="#ch04">04 — Context Windows</a></li>
<li><a href="#ch05">05 — The Context Stack</a></li>
<li><a href="#ch06">06 — RAG vs. Agentic Search</a></li>
</ol></div>
<div class="toc-part"><div class="toc-part-name">Part 3 · Security</div><ol>
<li><a href="#ch07">07 — The Security Crisis</a></li>
<li><a href="#ch08">08 — Authorization at Scale</a></li>
<li><a href="#ch09">09 — Prompt Injection</a></li>
<li><a href="#ch10">10 — Sandboxing</a></li>
</ol></div>
<div class="toc-part"><div class="toc-part-name">Part 4 · Protocols</div><ol>
<li><a href="#ch11">11 — Model Context Protocol</a></li>
<li><a href="#ch12">12 — Agent-to-Agent (A2A)</a></li>
<li><a href="#ch13">13 — AGENTS.md</a></li>
</ol></div>
<div class="toc-part"><div class="toc-part-name">Part 5 · Observability</div><ol>
<li><a href="#ch14">14 — Agent Traces</a></li>
<li><a href="#ch15">15 — Cost Tracking</a></li>
<li><a href="#ch16">16 — Incident Response</a></li>
</ol></div>
<div class="toc-part"><div class="toc-part-name">Part 6 · Orchestration</div><ol>
<li><a href="#ch17">17 — The Agent Loop</a></li>
<li><a href="#ch18">18 — Multi-Agent Systems</a></li>
<li><a href="#ch19">19 — Agent Memory</a></li>
</ol></div>
<div class="toc-part"><div class="toc-part-name">Part 7 · Team Practices</div><ol>
<li><a href="#ch20">20 — AI Fatigue</a></li>
<li><a href="#ch21">21 — The Conductor Model</a></li>
<li><a href="#ch22">22 — Maturity Model</a></li>
</ol></div>
<div class="toc-part"><div class="toc-part-name">Part 8 · Production</div><ol>
<li><a href="#ch23">23 — First Agent in Production</a></li>
<li><a href="#ch24">24 — Security Checklist</a></li>
<li><a href="#ch25">25 — Measuring Impact</a></li>
</ol></div>
<div class="toc-part"><div class="toc-part-name">Part 9 · Engineering</div><ol>
<li><a href="#ch26">26 — Evaluation & Testing</a></li>
<li><a href="#ch27">27 — Enterprise & Vendor</a></li>
<li><a href="#ch28">28 — Cost Control</a></li>
<li><a href="#ch29">29 — Governance</a></li>
<li><a href="#ch30">30 — Structured Outputs</a></li>
<li><a href="#ch31">31 — Model Routing</a></li>
</ol></div>
<div class="toc-part"><div class="toc-part-name">Part 10 · Sustainability</div><ol>
<li><a href="#ch32">32 — Backpressure</a></li>
<li><a href="#ch33">33 — Adoption Playbook</a></li>
</ol></div>
</div>
</div>
<!-- ═══════════════════════════════════════════
PART 1 · FOUNDATIONS
═══════════════════════════════════════════ -->
<div class="part-header">
<div class="part-num-badge">Part 01 — 3 Chapters</div>
<div class="part-title">Foundations</div>
<p class="part-desc">What agents actually are, why the capability jump happened, and the standards that will govern everything.</p>
</div>
<!-- CH01 -->
<details class="chapter" id="ch01">
<summary class="chapter-summary">
<span class="ch-num">Ch 01</span>
<span class="ch-info">
<span class="ch-title">The Agentic Engineering Landscape</span>
<span class="ch-tldr">What separates an agent from a chatbot, and why the difference is a production-grade engineering problem.</span>
</span>
<span class="ch-arrow">+</span>
</summary>
<div class="chapter-body">
<div class="tldr"><strong>TL;DR</strong><span>A chatbot is a function: text in, text out. An agent is a loop: it observes, decides, acts, and observes again until a goal is met. That single structural difference — autonomy over time — changes every engineering requirement.</span></div>
<h2>The loop is the architecture</h2>
<p>Strip away the marketing and an AI agent is a program that uses a language model to decide what to do next. It operates in a loop: observe the environment, decide on an action, execute it, observe the result, decide again. The loop continues until the goal is achieved or a termination condition is met.</p>
<!-- FIGURE 1.1: Agent loop as orbital cycle — animated red dot -->
<div class="diagram">
<svg viewBox="0 0 500 280" width="500" height="280" xmlns="http://www.w3.org/2000/svg" style="overflow:visible;">
<defs>
<marker id="arw1" markerWidth="7" markerHeight="7" refX="5" refY="3.5" orient="auto">
<path d="M0,1 L5,3.5 L0,6 Z" fill="#111"/>
</marker>
<style>
@keyframes orb01a{0%{offset-distance:0%;}100%{offset-distance:100%;}}
.orb01a{
offset-path:path('M250,52 C340,52 390,118 390,160 C390,202 340,268 250,268 C160,268 110,202 110,160 C110,118 160,52 250,52 Z');
offset-distance:0%;
animation:orb01a 4s linear infinite;
}
</style>
</defs>
<!-- thin guide ring -->
<ellipse cx="250" cy="160" rx="140" ry="108" fill="none" stroke="#e8e5de" stroke-width="1"/>
<!-- OBSERVE — top -->
<rect x="208" y="22" width="84" height="56" rx="2" fill="white" stroke="#111" stroke-width="1.5"/>
<text x="250" y="43" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="9" font-weight="600" fill="#111" letter-spacing=".14em">OBSERVE</text>
<text x="250" y="57" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">read files</text>
<text x="250" y="69" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">call APIs</text>
<!-- PLAN — left -->
<rect x="30" y="132" width="84" height="56" rx="2" fill="white" stroke="#111" stroke-width="1.5"/>
<text x="72" y="153" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="9" font-weight="600" fill="#111" letter-spacing=".14em">PLAN</text>
<text x="72" y="167" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">LLM decides</text>
<text x="72" y="179" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">next action</text>
<!-- ACT — right -->
<rect x="386" y="132" width="84" height="56" rx="2" fill="white" stroke="#111" stroke-width="1.5"/>
<text x="428" y="153" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="9" font-weight="600" fill="#111" letter-spacing=".14em">ACT</text>
<text x="428" y="167" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">execute tool</text>
<text x="428" y="179" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">or write output</text>
<!-- GOAL — bottom, filled black -->
<rect x="208" y="242" width="84" height="56" rx="2" fill="#111" stroke="#111" stroke-width="1.5"/>
<text x="250" y="263" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="9" font-weight="600" fill="white" letter-spacing=".14em">GOAL</text>
<text x="250" y="277" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#888">done?</text>
<text x="250" y="289" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#888">if not, loop</text>
<!-- direction arrows (quarter-arc) -->
<path d="M265,78 C310,85 382,120 385,132" fill="none" stroke="#111" stroke-width="1" marker-end="url(#arw1)" opacity=".35"/>
<path d="M386,189 C370,236 310,260 265,262" fill="none" stroke="#111" stroke-width="1" marker-end="url(#arw1)" opacity=".35"/>
<path d="M208,262 C152,256 112,212 114,189" fill="none" stroke="#111" stroke-width="1" marker-end="url(#arw1)" opacity=".35"/>
<path d="M114,132 C120,100 188,82 208,78" fill="none" stroke="#111" stroke-width="1" marker-end="url(#arw1)" opacity=".35"/>
<!-- animated dot -->
<circle class="orb01a" r="5" fill="#c0392b"/>
<!-- centre label -->
<text x="250" y="155" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="10" fill="#ccc" letter-spacing=".1em">AGENT</text>
<text x="250" y="170" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="10" fill="#ccc" letter-spacing=".1em">LOOP</text>
</svg>
<figcaption>FIGURE 1.1 — The agent loop. A red dot travels the cycle continuously until the GOAL node registers completion. Every production agent — simple or complex — runs this structure.</figcaption>
</div>
<h2>Chatbot vs. Agent: the full dimension table</h2>
<p>The autonomy gap changes every engineering requirement. This is not a shallow distinction — it cascades through authorization, observability, failure modes, and cost.</p>
<!-- FIGURE 1.2: Comparison table rendered as visual grid -->
<div class="diagram">
<svg viewBox="0 0 500 260" width="500" height="260" xmlns="http://www.w3.org/2000/svg">
<defs>
<style>
.thl{font-family:'JetBrains Mono',monospace;font-size:9px;font-weight:600;letter-spacing:.12em;text-transform:uppercase;}
.tdl{font-family:'JetBrains Mono',monospace;font-size:9px;}
.dim{font-family:'JetBrains Mono',monospace;font-size:8px;fill:#999;}
</style>
</defs>
<!-- header row -->
<rect x="0" y="0" width="160" height="26" fill="#f0ede6"/>
<rect x="161" y="0" width="164" height="26" fill="#222"/>
<rect x="326" y="0" width="174" height="26" fill="#111"/>
<text x="80" y="17" text-anchor="middle" class="thl" fill="#999">DIMENSION</text>
<text x="243" y="17" text-anchor="middle" class="thl" fill="#ccc">CHATBOT</text>
<text x="413" y="17" text-anchor="middle" class="thl" fill="white">AGENT</text>
<!-- rows -->
<!-- row data: [y, dim, chatbot_val, agent_val, agent_is_red] -->
<!-- Actions -->
<rect x="0" y="27" width="160" height="26" fill="#f8f7f4"/>
<rect x="161" y="27" width="164" height="26" fill="white" stroke="#eee" stroke-width=".5"/>
<rect x="326" y="27" width="174" height="26" fill="white" stroke="#eee" stroke-width=".5"/>
<text x="8" y="44" class="dim">Actions</text>
<text x="169" y="44" class="tdl" fill="#555">Generates text</text>
<text x="334" y="44" class="tdl" fill="#c0392b">Executes code, calls APIs</text>
<!-- Autonomy -->
<rect x="0" y="54" width="160" height="26" fill="#f0ede6"/>
<rect x="161" y="54" width="164" height="26" fill="white" stroke="#eee" stroke-width=".5"/>
<rect x="326" y="54" width="174" height="26" fill="white" stroke="#eee" stroke-width=".5"/>
<text x="8" y="71" class="dim">Autonomy</text>
<text x="169" y="71" class="tdl" fill="#555">Responds to prompts</text>
<text x="334" y="71" class="tdl" fill="#111">Decides what to do next</text>
<!-- Duration -->
<rect x="0" y="81" width="160" height="26" fill="#f8f7f4"/>
<rect x="161" y="81" width="164" height="26" fill="white" stroke="#eee" stroke-width=".5"/>
<rect x="326" y="81" width="174" height="26" fill="white" stroke="#eee" stroke-width=".5"/>
<text x="8" y="98" class="dim">Duration</text>
<text x="169" y="98" class="tdl" fill="#555">Single turn</text>
<text x="334" y="98" class="tdl" fill="#111">Minutes to hours</text>
<!-- Risk -->
<rect x="0" y="108" width="160" height="26" fill="#f0ede6"/>
<rect x="161" y="108" width="164" height="26" fill="white" stroke="#eee" stroke-width=".5"/>
<rect x="326" y="108" width="174" height="26" fill="white" stroke="#eee" stroke-width=".5"/>
<text x="8" y="125" class="dim">Risk</text>
<text x="169" y="125" class="tdl" fill="#555">Wrong answer</text>
<text x="334" y="125" class="tdl" fill="#c0392b">Wrong action: data loss</text>
<!-- Auth -->
<rect x="0" y="135" width="160" height="26" fill="#f8f7f4"/>
<rect x="161" y="135" width="164" height="26" fill="white" stroke="#eee" stroke-width=".5"/>
<rect x="326" y="135" width="174" height="26" fill="white" stroke="#eee" stroke-width=".5"/>
<text x="8" y="152" class="dim">Authorization</text>
<text x="169" y="152" class="tdl" fill="#555">User's permissions</text>
<text x="334" y="152" class="tdl" fill="#111">Needs its own model</text>
<!-- Observability -->
<rect x="0" y="162" width="160" height="26" fill="#f0ede6"/>
<rect x="161" y="162" width="164" height="26" fill="white" stroke="#eee" stroke-width=".5"/>
<rect x="326" y="162" width="174" height="26" fill="white" stroke="#eee" stroke-width=".5"/>
<text x="8" y="179" class="dim">Observability</text>
<text x="169" y="179" class="tdl" fill="#555">Log the response</text>
<text x="334" y="179" class="tdl" fill="#111">Trace every decision</text>
<!-- Failure mode -->
<rect x="0" y="189" width="160" height="26" fill="#f8f7f4"/>
<rect x="161" y="189" width="164" height="26" fill="white" stroke="#eee" stroke-width=".5"/>
<rect x="326" y="189" width="174" height="26" fill="white" stroke="#eee" stroke-width=".5"/>
<text x="8" y="206" class="dim">Failure mode</text>
<text x="169" y="206" class="tdl" fill="#555">Bad text</text>
<text x="334" y="206" class="tdl" fill="#c0392b">Production incident</text>
<!-- border -->
<rect x="0" y="0" width="500" height="215" fill="none" stroke="#ddd" stroke-width="1"/>
<line x1="160" y1="0" x2="160" y2="215" stroke="#ddd" stroke-width="1"/>
<line x1="325" y1="0" x2="325" y2="215" stroke="#ddd" stroke-width="1"/>
</svg>
<figcaption>FIGURE 1.2 — Chatbot vs. agent across seven engineering dimensions. Red cells mark dimensions where agents introduce qualitatively new requirements — not just more of the same.</figcaption>
</div>
<h2>The four capability levels</h2>
<p>Not all agents are equal. The capability spectrum determines the engineering requirements — and where most teams in February 2026 actually are.</p>
<!-- FIGURE 1.3: Capability spectrum as ascending horizontal axis chart -->
<div class="diagram">
<svg viewBox="0 0 500 160" width="500" height="160" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="ax1s" markerWidth="6" markerHeight="6" refX="5" refY="3" orient="auto">
<path d="M0,0 L5,3 L0,6 Z" fill="#111"/>
</marker>
</defs>
<!-- baseline axis -->
<line x1="30" y1="100" x2="480" y2="100" stroke="#111" stroke-width="1.5" marker-end="url(#ax1s)"/>
<text x="255" y="148" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999" letter-spacing=".08em">ENGINEERING REQUIREMENT</text>
<!-- L1 -->
<rect x="35" y="72" width="90" height="28" fill="#f0ede6" stroke="#ddd" stroke-width="1"/>
<text x="80" y="88" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="9" fill="#999" letter-spacing=".1em">L1 COMPLETE</text>
<text x="80" y="55" text-anchor="middle" font-family="DM Sans,sans-serif" font-size="10" fill="#aaa">Copilot inline</text>
<text x="80" y="67" text-anchor="middle" font-family="DM Sans,sans-serif" font-size="10" fill="#aaa">suggestions</text>
<!-- L2 -->
<rect x="140" y="56" width="90" height="44" fill="#ddd" stroke="#bbb" stroke-width="1"/>
<text x="185" y="76" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="9" fill="#777" letter-spacing=".1em">L2 CHAT</text>
<text x="185" y="40" text-anchor="middle" font-family="DM Sans,sans-serif" font-size="10" fill="#777">Cursor chat,</text>
<text x="185" y="52" text-anchor="middle" font-family="DM Sans,sans-serif" font-size="10" fill="#777">Claude.ai</text>
<!-- L3 - most teams here -->
<rect x="245" y="36" width="90" height="64" fill="#555" stroke="#333" stroke-width="1"/>
<text x="290" y="56" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="9" fill="white" letter-spacing=".1em">L3 COMMAND</text>
<text x="290" y="22" text-anchor="middle" font-family="DM Sans,sans-serif" font-size="10" fill="#c0392b">← most teams</text>
<text x="290" y="34" text-anchor="middle" font-family="DM Sans,sans-serif" font-size="10" fill="#555">Claude Code,</text>
<!-- L4 -->
<rect x="350" y="16" width="90" height="84" fill="#111" stroke="#111" stroke-width="1"/>
<text x="395" y="36" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="9" fill="white" letter-spacing=".1em">L4 BACKGROUND</text>
<text x="395" y="10" text-anchor="middle" font-family="DM Sans,sans-serif" font-size="10" fill="#888">GH Agentic</text>
<!-- tick labels on axis -->
<text x="80" y="115" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#ccc">Minimal</text>
<text x="185" y="115" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">Moderate</text>
<text x="290" y="115" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#555">Significant</text>
<text x="395" y="115" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#111">Critical</text>
</svg>
<figcaption>FIGURE 1.3 — Agent capability spectrum. Bar height represents engineering requirement complexity. Most teams in Feb 2026 are at L2–L3; the transition from L3 to L4 is where this guide is essential.</figcaption>
</div>
<div class="level-strip">
<div class="level-item"><div class="level-num">L1</div><div class="level-name">Completion</div><div class="level-desc">Inline suggestions only. No tools, no external access. Developer reviews every character.</div></div>
<div class="level-item"><div class="level-num">L2</div><div class="level-name">Chat</div><div class="level-desc">Natural language requests. Generates multi-line code. Output is manually copied into the codebase.</div></div>
<div class="level-item"><div class="level-num">L3</div><div class="level-name">Command</div><div class="level-desc">Reads/writes files, runs commands, opens PRs. Operates autonomously within a session.</div></div>
<div class="level-item"><div class="level-num">L4</div><div class="level-name">Background</div><div class="level-desc">Runs without supervision. Monitors repos, fixes bugs, creates PRs on schedule — no human trigger.</div></div>
</div>
<h2>The agentic stack: six layers</h2>
<p>The engineering discipline of this guide is organised by these six layers. Teams that succeed start at the bottom and work up. Teams that fail start at the top (pick a tool, start using it) and hit every layer as a surprise.</p>
<!-- FIGURE 1.4: Six-layer stack -->
<div class="diagram">
<svg viewBox="0 0 500 220" width="500" height="220" xmlns="http://www.w3.org/2000/svg">
<defs>
<style>.slabel{font-family:'JetBrains Mono',monospace;font-size:9px;letter-spacing:.12em;font-weight:600;}
.sdesc{font-family:'JetBrains Mono',monospace;font-size:8px;fill:#aaa;}</style>
</defs>
<!-- Layer 6: Human (top) -->
<rect x="10" y="10" width="480" height="28" fill="white" stroke="#ddd" stroke-width="1"/>
<text x="20" y="28" class="slabel" fill="#888">06 · HUMAN LAYER</text>
<text x="210" y="28" class="sdesc">team practices · review processes · org patterns</text>
<!-- Layer 5: Security (spans full stack) — indicated by right bracket -->
<rect x="10" y="44" width="480" height="28" fill="#fff0ee" stroke="#c0392b" stroke-width="1"/>
<text x="20" y="62" class="slabel" fill="#c0392b">05 · SECURITY (spans all layers)</text>
<text x="240" y="62" class="sdesc" style="fill:#c0392b;opacity:.7;">auth · sandbox · injection · audit</text>
<!-- Layer 4: Orchestration -->
<rect x="10" y="78" width="480" height="28" fill="#f7f6f2" stroke="#ddd" stroke-width="1"/>
<text x="20" y="96" class="slabel" fill="#555">04 · ORCHESTRATION</text>
<text x="210" y="96" class="sdesc">agent loop · multi-agent · memory</text>
<!-- Layer 3: Protocol -->
<rect x="10" y="112" width="480" height="28" fill="#f0ede6" stroke="#ddd" stroke-width="1"/>
<text x="20" y="130" class="slabel" fill="#444">03 · PROTOCOL</text>
<text x="210" y="130" class="sdesc">MCP · A2A · AGENTS.md</text>
<!-- Layer 2: Context -->
<rect x="10" y="146" width="480" height="28" fill="#e8e5de" stroke="#ddd" stroke-width="1"/>
<text x="20" y="164" class="slabel" fill="#333">02 · CONTEXT</text>
<text x="210" y="164" class="sdesc">retrieval · compression · token budget</text>
<!-- Layer 1: Model (bottom, darkest) -->
<rect x="10" y="180" width="480" height="28" fill="#111" stroke="#111"/>
<text x="20" y="198" class="slabel" fill="white">01 · MODEL LAYER</text>
<text x="210" y="198" class="sdesc" style="fill:#666;">frontier LLMs · inference · routing</text>
</svg>
<figcaption>FIGURE 1.4 — The agentic engineering stack. Security (Layer 5, red) spans every layer. Most teams start at Layer 6 and encounter the lower layers as production incidents.</figcaption>
</div>
<h2>The numbers, February 2026</h2>
<div class="stat-grid">
<div class="stat-card"><div class="stat-val">80%</div><div class="stat-label">of Fortune 500 using AI agents actively (Microsoft Security, Feb 2026)</div></div>
<div class="stat-card"><div class="stat-val">60%</div><div class="stat-label">of coding tasks are AI-assisted (Anthropic, Feb 2026)</div></div>
<div class="stat-card"><div class="stat-val">65%</div><div class="stat-label">of enterprises already deploying agents (CrewAI State of Agentic AI)</div></div>
<div class="stat-card"><div class="stat-val red">20%</div><div class="stat-label">of those enterprises have meaningful security controls around agents</div></div>
</div>
<div class="insight"><p>"You cannot prompt your way out of garbage context." The model you choose matters. The prompt matters. But what you put in the context window matters more than both combined. That gap between 80% adoption and 20% security coverage is the crisis this guide addresses.</p></div>
</div>
</details>
<!-- CH02 -->
<details class="chapter" id="ch02">
<summary class="chapter-summary">
<span class="ch-num">Ch 02</span>
<span class="ch-info">
<span class="ch-title">The Capability Jump</span>
<span class="ch-tldr">What actually changed in late 2025, and why "year of engineering work in one hour" isn't hype.</span>
</span>
<span class="ch-arrow">+</span>
</summary>
<div class="chapter-body">
<div class="tldr"><strong>TL;DR</strong><span>In late 2025, Claude Opus 4.5 and GPT-5.2 crossed an invisible threshold. Engineers who'd been sceptical started saying "it built in one hour what we built last year." By February 2026, four frontier models from three labs landed in fourteen days, ending the "pick one best model" era. Model routing is now a production requirement.</span></div>
<h2>The inflection point</h2>
<p>Simon Willison, whose observations carry more weight than most benchmarks: <em>"It genuinely feels like GPT-5.2 and Opus 4.5 represent an inflection point — one of those moments where models get incrementally better in a way that tips across an invisible capability line where suddenly a whole bunch of much harder coding problems open up."</em></p>
<blockquote>Jaana Dogan, Principal Engineer at Google: "I gave Claude Code a description of the problem, it generated what we built last year in an hour."</blockquote>
<!-- FIGURE 2.1: Timeline with annotated jumps — Howard Marks style -->
<div class="diagram">
<svg viewBox="0 0 500 180" width="500" height="180" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="ax2t" markerWidth="6" markerHeight="6" refX="5" refY="3" orient="auto">
<path d="M0,0 L5,3 L0,6 Z" fill="#111"/>
</marker>
</defs>
<!-- axis -->
<line x1="40" y1="120" x2="480" y2="120" stroke="#111" stroke-width="1.5" marker-end="url(#ax2t)"/>
<line x1="40" y1="30" x2="40" y2="125" stroke="#111" stroke-width="1.5" marker-end="url(#ax2t)"/>
<text x="22" y="78" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999" text-anchor="middle" transform="rotate(-90,22,78)">CAPABILITY</text>
<!-- baseline capability curve -->
<path d="M45,115 C80,113 130,108 180,100 C230,92 270,88 290,115 C310,87 340,60 380,40 C400,32 430,28 470,25"
fill="none" stroke="#111" stroke-width="2"
class="draw-on" style="--path-len:700;"/>
<!-- Step jump vertical line at ~x=290 -->
<line x1="290" y1="35" x2="290" y2="118" stroke="#c0392b" stroke-width="1.5" stroke-dasharray="4,3"
class="draw-on" style="--path-len:200;"/>
<!-- tick dates -->
<line x1="100" y1="117" x2="100" y2="124" stroke="#111" stroke-width="1"/>
<text x="100" y="136" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">2023</text>
<line x1="185" y1="117" x2="185" y2="124" stroke="#111" stroke-width="1"/>
<text x="185" y="136" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">2024</text>
<line x1="290" y1="117" x2="290" y2="124" stroke="#c0392b" stroke-width="1"/>
<text x="290" y="136" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#c0392b">Nov 2025</text>
<text x="290" y="148" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#c0392b">Opus 4.5 · GPT-5.2</text>
<line x1="385" y1="117" x2="385" y2="124" stroke="#111" stroke-width="1"/>
<text x="385" y="136" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">Feb 2026</text>
<text x="385" y="148" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">4 models, 14 days</text>
<!-- annotation for "invisible line" -->
<text x="310" y="58" font-family="'JetBrains Mono',monospace" font-size="8" fill="#c0392b">capability</text>
<text x="310" y="70" font-family="'JetBrains Mono',monospace" font-size="8" fill="#c0392b">threshold</text>
<text x="310" y="82" font-family="'JetBrains Mono',monospace" font-size="8" fill="#c0392b">crossed</text>
<text x="455" y="23" font-family="'JetBrains Mono',monospace" font-size="8" fill="#555">now</text>
</svg>
<figcaption>FIGURE 2.1 — The capability jump timeline. Gradual improvement (2023–2024), then a threshold crossing at Nov 2025 with Opus 4.5 + GPT-5.2. The February 2026 cluster made model routing a necessity, not an optimisation.</figcaption>
</div>
<h2>Five implications for engineering teams</h2>
<h3>1 — Agents are management problems</h3>
<p>The skills that make someone effective with agents are management skills: clear communication of goals, providing necessary context, breaking down complex tasks, giving actionable feedback. The engineer who writes the clearest task descriptions outperforms the engineer who writes the best code by hand.</p>
<h3>2 — Output scales faster than review capacity</h3>
<p>A team of five engineers produces roughly 25 PRs per week. Each PR takes 30–60 minutes to review. Now add agents. The same team might produce 75–100 PRs per week. Review time triples or quadruples; team size doesn't change.</p>
<!-- FIGURE 2.2: Review burden chart — Howard Marks bar comparison -->
<div class="diagram">
<svg viewBox="0 0 440 160" width="440" height="160" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="ax2r" markerWidth="6" markerHeight="6" refX="5" refY="3" orient="auto">
<path d="M0,0 L5,3 L0,6 Z" fill="#111"/>
</marker>
</defs>
<!-- axes -->
<line x1="50" y1="20" x2="50" y2="120" stroke="#111" stroke-width="1.5" marker-end="url(#ax2r)"/>
<line x1="50" y1="120" x2="420" y2="120" stroke="#111" stroke-width="1.5"/>
<text x="28" y="72" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999" text-anchor="middle" transform="rotate(-90,28,72)">PRs / WEEK</text>
<!-- Before: 25 PRs -->
<rect x="70" y="97" width="60" height="23" fill="#ddd" stroke="#bbb" stroke-width="1" class="fill-bar"/>
<text x="100" y="90" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="10" fill="#555">25</text>
<text x="100" y="134" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">Before</text>
<text x="100" y="145" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">agents</text>
<!-- After: 75-100 PRs -->
<rect x="175" y="46" width="60" height="74" fill="#555" stroke="#444" stroke-width="1" class="fill-bar"/>
<text x="205" y="39" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="10" fill="#111">75–100</text>
<text x="205" y="134" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#111">After agents</text>
<text x="205" y="145" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#111">(same team)</text>
<!-- Review hours -->
<!-- Before: 12-25 hrs -->
<rect x="285" y="90" width="60" height="30" fill="#ddd" stroke="#bbb" stroke-width="1" class="fill-bar"/>
<text x="315" y="82" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="10" fill="#555">12–25h</text>
<text x="315" y="134" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">Review hrs</text>
<text x="315" y="145" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">before</text>
<!-- After: 40-80 hrs -->
<rect x="360" y="30" width="60" height="90" fill="#c0392b" stroke="#c0392b" stroke-width="1" class="fill-bar"/>
<text x="390" y="22" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="10" fill="#c0392b">40–80h</text>
<text x="390" y="134" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#c0392b">Review hrs</text>
<text x="390" y="145" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#c0392b">after</text>
</svg>
<figcaption>FIGURE 2.2 — The review burden problem. PR volume can 4× with agents; review hours follow if no automated gates exist. The solution is a two-layer review process (automated + human judgment) covered in Ch. 24.</figcaption>
</div>
<h3>3 — The documentation business is disrupted</h3>
<p>Tailwind Labs (Jan 2026): documentation traffic down 40%, revenue down 80% — not because Tailwind is less popular, but because AI generates Tailwind code directly. Any business model built on people reading docs faces the same dynamic.</p>
<h3>4 — The junior engineer pipeline is disrupted</h3>
<p>Tasks agents handle well are exactly the tasks traditionally assigned to juniors: boilerplate, simple bugs, test coverage, documentation. The emerging pattern: juniors shift from writing code to reviewing agent-generated code — which is actually a faster path to engineering judgment if mentored correctly.</p>
<h3>5 — Model routing replaces model selection</h3>
<p>No single model dominates all tasks. GPT-5.3-Codex leads Terminal-Bench (75.1%). Opus 4.6 leads SWE-bench Verified (80.8%). Gemini 3.1 Pro leads long-context tasks (1M token window). The "pick one model" era is over.</p>
<!-- FIGURE 2.3: Model pricing bar chart -->
<div class="diagram">
<svg viewBox="0 0 500 180" width="500" height="180" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="ax2p" markerWidth="6" markerHeight="6" refX="5" refY="3" orient="auto">
<path d="M0,0 L5,3 L0,6 Z" fill="#111"/>
</marker>
</defs>
<!-- x axis -->
<line x1="140" y1="150" x2="480" y2="150" stroke="#111" stroke-width="1.5" marker-end="url(#ax2p)"/>
<text x="310" y="168" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">COST per 100K input + 10K output (USD)</text>
<!-- model rows, y pos 22, 42, 62, 82, 102, 122 -->
<!-- Opus 4.6: $0.750 → full bar at ~340px wide (0.75 / 0.75 * 330) = 330 -->
<text x="135" y="30" text-anchor="end" font-family="'JetBrains Mono',monospace" font-size="8" fill="#111">Opus 4.6</text>
<rect x="140" y="20" width="330" height="16" fill="#111" class="fill-bar"/>
<text x="476" y="32" font-family="'JetBrains Mono',monospace" font-size="8" fill="#111">$0.75</text>
<!-- Sonnet 4.6: $0.450 → 198 -->
<text x="135" y="52" text-anchor="end" font-family="'JetBrains Mono',monospace" font-size="8" fill="#555">Sonnet 4.6</text>
<rect x="140" y="42" width="198" height="16" fill="#444" class="fill-bar"/>
<text x="344" y="54" font-family="'JetBrains Mono',monospace" font-size="8" fill="#444">$0.45</text>
<!-- GPT-5.2: $0.315 → 138 -->
<text x="135" y="72" text-anchor="end" font-family="'JetBrains Mono',monospace" font-size="8" fill="#555">GPT-5.2</text>
<rect x="140" y="62" width="138" height="16" fill="#666" class="fill-bar"/>
<text x="284" y="74" font-family="'JetBrains Mono',monospace" font-size="8" fill="#666">$0.315</text>
<!-- Gemini 3.1 Pro: $0.320 → 141 -->
<text x="135" y="92" text-anchor="end" font-family="'JetBrains Mono',monospace" font-size="8" fill="#555">Gemini 3.1 Pro</text>
<rect x="140" y="82" width="141" height="16" fill="#777" class="fill-bar"/>
<text x="287" y="94" font-family="'JetBrains Mono',monospace" font-size="8" fill="#777">$0.32</text>
<!-- Haiku 4: $0.150 → 66 -->
<text x="135" y="112" text-anchor="end" font-family="'JetBrains Mono',monospace" font-size="8" fill="#888">Haiku 4</text>
<rect x="140" y="102" width="66" height="16" fill="#aaa" class="fill-bar"/>
<text x="212" y="114" font-family="'JetBrains Mono',monospace" font-size="8" fill="#888">$0.15</text>
<!-- GPT-5.2-mini: $0.021 → 9 -->
<text x="135" y="132" text-anchor="end" font-family="'JetBrains Mono',monospace" font-size="8" fill="#aaa">GPT-5.2 mini</text>
<rect x="140" y="122" width="9" height="16" fill="#ccc" class="fill-bar"/>
<text x="155" y="134" font-family="'JetBrains Mono',monospace" font-size="8" fill="#aaa">$0.021</text>
<!-- Gemini Flash: $0.011 → 4 -->
<text x="135" y="152" text-anchor="end" font-family="'JetBrains Mono',monospace" font-size="8" fill="#c0392b">Gemini Flash</text>
<rect x="140" y="142" width="4" height="6" fill="#c0392b" class="fill-bar"/>
<text x="150" y="152" font-family="'JetBrains Mono',monospace" font-size="8" fill="#c0392b">$0.011 ← 35× cheaper than Opus</text>
</svg>
<figcaption>FIGURE 2.3 — Model cost comparison for 100K input + 10K output tokens. The 35× cost gap between Opus 4.6 and Gemini Flash makes model routing a financial imperative. Routing 70% of tasks to small models cuts total LLM spend by 60–70%.</figcaption>
</div>
<div class="analogy"><strong>Analogy</strong><span>No logistics company uses a jumbo jet to deliver a single letter. Frontier models are the jumbo jet — reserved for the tasks that genuinely need that capacity. Routing is the dispatch system that assigns the right vehicle to each delivery.</span></div>
</div>
</details>
<!-- CH03 -->
<details class="chapter" id="ch03">
<summary class="chapter-summary">
<span class="ch-num">Ch 03</span>
<span class="ch-info">
<span class="ch-title">The Agentic AI Foundation & Standards</span>
<span class="ch-tldr">On Dec 9 2025, Anthropic, OpenAI, and Block announced the AAIF under the Linux Foundation. Here is what it means.</span>
</span>
<span class="ch-arrow">+</span>
</summary>
<div class="chapter-body">
<div class="tldr"><strong>TL;DR</strong><span>The AAIF mirrors the pattern of Linux (OS), Kubernetes (container orchestration), and OpenTelemetry (observability): competitors collaborate on infrastructure standards so differentiation happens at higher layers. Three founding projects — MCP, Goose, AGENTS.md — standardise tool integration, agent architecture, and codebase onboarding respectively. Three critical gaps remain: security auth, authorization models, and observability semantics.</span></div>
<h2>Why competitors standardise infrastructure</h2>
<p>On December 9, 2025, Anthropic, OpenAI, and Block announced the Agentic AI Foundation under the Linux Foundation, with Google, Microsoft, AWS, Cloudflare, and Bloomberg as supporters. These companies compete fiercely on models. Yet they're collaborating on infrastructure standards.</p>
<div class="analogy"><strong>Pattern recognition</strong><span>Linux standardised operating systems. Kubernetes standardised container orchestration. OpenTelemetry standardised observability. In each case, vendors realised that standardising the infrastructure layer accelerated adoption for everyone, while differentiation happened at higher layers. AAIF is the same play.</span></div>
<!-- FIGURE 3.1: The three AAIF founding projects as a side-by-side comparison -->
<div class="diagram">
<svg viewBox="0 0 500 200" width="500" height="200" xmlns="http://www.w3.org/2000/svg">
<defs>
<style>
.phead{font-family:'JetBrains Mono',monospace;font-size:10px;font-weight:600;letter-spacing:.14em;}
.pbody{font-family:'JetBrains Mono',monospace;font-size:8px;fill:#555;}
.ptag{font-family:'JetBrains Mono',monospace;font-size:7px;fill:#999;}
</style>
</defs>
<!-- MCP column -->
<rect x="10" y="10" width="150" height="175" fill="white" stroke="#111" stroke-width="1.5"/>
<rect x="10" y="10" width="150" height="24" fill="#111"/>
<text x="85" y="27" text-anchor="middle" class="phead" fill="white">MCP</text>
<text x="85" y="50" text-anchor="middle" class="ptag">donated by Anthropic</text>
<text x="85" y="68" text-anchor="middle" class="pbody">Universal protocol</text>
<text x="85" y="82" text-anchor="middle" class="pbody">for tool integration.</text>
<text x="85" y="96" text-anchor="middle" class="pbody">Agent discovers +</text>
<text x="85" y="110" text-anchor="middle" class="pbody">calls any tool via</text>
<text x="85" y="124" text-anchor="middle" class="pbody">one standard API.</text>
<line x1="25" y1="140" x2="145" y2="140" stroke="#eee" stroke-width="1"/>
<text x="85" y="155" text-anchor="middle" class="pbody" style="fill:#c0392b;">10k+ active servers</text>
<text x="85" y="168" text-anchor="middle" class="pbody" style="fill:#c0392b;">97M monthly downloads</text>
<!-- Goose column -->
<rect x="175" y="10" width="150" height="175" fill="white" stroke="#555" stroke-width="1"/>
<rect x="175" y="10" width="150" height="24" fill="#555"/>
<text x="250" y="27" text-anchor="middle" class="phead" fill="white">GOOSE</text>
<text x="250" y="50" text-anchor="middle" class="ptag">donated by Block</text>
<text x="250" y="68" text-anchor="middle" class="pbody">Open-source agent</text>
<text x="250" y="82" text-anchor="middle" class="pbody">reference impl.</text>
<text x="250" y="96" text-anchor="middle" class="pbody">MCP-native, cost-</text>
<text x="250" y="110" text-anchor="middle" class="pbody">tracked, killable.</text>
<text x="250" y="124" text-anchor="middle" class="pbody">Study its patterns</text>
<text x="250" y="138" text-anchor="middle" class="pbody">even if you don't</text>
<text x="250" y="152" text-anchor="middle" class="pbody">use it directly.</text>
<text x="250" y="168" text-anchor="middle" class="ptag">github.com/block/goose</text>
<!-- AGENTS.md column -->
<rect x="340" y="10" width="150" height="175" fill="white" stroke="#ddd" stroke-width="1"/>
<rect x="340" y="10" width="150" height="24" fill="#888"/>
<text x="415" y="27" text-anchor="middle" class="phead" fill="white">AGENTS.md</text>
<text x="415" y="50" text-anchor="middle" class="ptag">donated by OpenAI</text>
<text x="415" y="68" text-anchor="middle" class="pbody">Standard format for</text>
<text x="415" y="82" text-anchor="middle" class="pbody">AI coding agent</text>
<text x="415" y="96" text-anchor="middle" class="pbody">instructions. Think</text>
<text x="415" y="110" text-anchor="middle" class="pbody">README.md but for</text>
<text x="415" y="124" text-anchor="middle" class="pbody">machine consumers.</text>
<line x1="355" y1="140" x2="475" y2="140" stroke="#eee" stroke-width="1"/>
<text x="415" y="155" text-anchor="middle" class="pbody" style="fill:#c0392b;">60k+ repos have one</text>
<text x="415" y="168" text-anchor="middle" class="ptag">10 min to write. Write it now.</text>
</svg>
<figcaption>FIGURE 3.1 — The three AAIF founding projects. MCP handles tool integration (any agent, any tool). Goose is the reference production architecture. AGENTS.md is the machine-readable project onboarding file. All three are live and in widespread adoption.</figcaption>
</div>
<h2>The three standards beyond AAIF</h2>
<!-- FIGURE 3.2: Standards ecosystem connection diagram -->
<div class="diagram">
<svg viewBox="0 0 500 200" width="500" height="200" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arw3e" markerWidth="6" markerHeight="6" refX="5" refY="3" orient="auto">
<path d="M0,0 L5,3 L0,6 Z" fill="#555"/>
</marker>
<style>
@keyframes blink3{0%,100%{opacity:1;}50%{opacity:.3;}}
.blink3{animation:blink3 2s ease-in-out infinite;}
</style>
</defs>
<!-- Centre: Agent -->
<rect x="195" y="75" width="110" height="50" fill="#111" stroke="#111"/>
<text x="250" y="97" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="10" fill="white" letter-spacing=".1em">AGENT</text>
<text x="250" y="113" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#888">production system</text>
<!-- MCP — left (tools) -->
<rect x="20" y="20" width="120" height="44" fill="white" stroke="#111" stroke-width="1.5"/>
<text x="80" y="38" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="9" fill="#111" font-weight="600">MCP</text>
<text x="80" y="52" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#555">tool integration</text>
<line x1="142" y1="42" x2="193" y2="90" stroke="#555" stroke-width="1" marker-end="url(#arw3e)"/>
<!-- A2A — top right (agent comm) -->
<rect x="360" y="20" width="120" height="44" fill="white" stroke="#555" stroke-width="1"/>
<text x="420" y="38" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="9" fill="#555" font-weight="600">A2A (Google)</text>
<text x="420" y="52" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">agent ↔ agent</text>
<line x1="358" y1="42" x2="307" y2="90" stroke="#555" stroke-width="1" marker-end="url(#arw3e)"/>
<!-- OpenFGA — bottom left (auth) -->
<rect x="20" y="140" width="120" height="44" fill="white" stroke="#555" stroke-width="1"/>
<text x="80" y="158" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="9" fill="#555" font-weight="600">OpenFGA</text>
<text x="80" y="172" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">authorization (Zanzibar)</text>
<line x1="142" y1="162" x2="193" y2="118" stroke="#555" stroke-width="1" marker-end="url(#arw3e)"/>
<!-- OTel — bottom right (observability) -->
<rect x="360" y="140" width="120" height="44" fill="white" stroke="#555" stroke-width="1"/>
<text x="420" y="158" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="9" fill="#555" font-weight="600">OpenTelemetry</text>
<text x="420" y="172" text-anchor="middle" font-family="'JetBrains Mono',monospace" font-size="8" fill="#999">traces & spans</text>
<line x1="358" y1="162" x2="307" y2="118" stroke="#555" stroke-width="1" marker-end="url(#arw3e)"/>
<!-- pulse on agent box to show data flow -->
<rect x="195" y="75" width="110" height="50" fill="none" stroke="#c0392b" stroke-width="1.5" class="blink3"/>
</svg>
<figcaption>FIGURE 3.2 — Standards ecosystem around a production agent. MCP handles tool calls, A2A handles agent-to-agent delegation, OpenFGA handles fine-grained authorisation, OpenTelemetry handles traces. All four use open standards; all four are in active production use.</figcaption>
</div>
<h2>The three critical gaps</h2>
<p>AAIF is a foundation, not a complete solution. Three significant gaps remain — and they represent the most important unsolved problems in agent infrastructure today.</p>
<div class="concept-row">
<div class="concept-card"><div class="cc-num" style="color:#c0392b">1</div><div class="cc-title">Security Auth</div><div class="cc-desc">MCP defines how agents call tools, not how they authenticate. Over 8,000 public MCP servers have no authentication at all. Every implementation rolls its own — every implementation has its own vulnerabilities.</div></div>
<div class="concept-card"><div class="cc-num" style="color:#c0392b">2</div><div class="cc-title">Authorization</div><div class="cc-desc">Agents need fine-grained, context-dependent permissions that RBAC can't express. "Can read source code but not production secrets" requires Zanzibar-style relationship models. No standard yet.</div></div>
<div class="concept-card"><div class="cc-num" style="color:#c0392b">3</div><div class="cc-title">Observability Semantics</div><div class="cc-desc">OpenTelemetry is extending to agents, but span semantics for LLM calls and tool chains are still being defined. Every team inventing its own schema now faces a migration later.</div></div>
</div>
<h2>The open source stack</h2>
<table>
<tr><th>Layer</th><th>Tool</th><th>What it does</th></tr>
<tr><td>Model abstraction</td><td><code>LiteLLM</code></td><td>Unified API for 100+ LLM providers. Swap models with one config change.</td></tr>
<tr><td>Authorization</td><td><code>OpenFGA</code></td><td>Zanzibar-style relationship-based access control (CNCF Incubating).</td></tr>
<tr><td>Observability</td><td><code>Langfuse</code></td><td>AI-specific traces, cost attribution, prompt tracking, eval integration.</td></tr>
<tr><td>Sandboxing</td><td><code>gVisor</code></td><td>Application-level kernel isolation for agent execution environments.</td></tr>
<tr><td>Evaluation</td><td><code>Promptfoo</code></td><td>Config-driven evals for prompts and agents. Open source.</td></tr>
<tr><td>Vector DB</td><td><code>Qdrant / Chroma</code></td><td>Embedding-based retrieval for long-term agent memory.</td></tr>
<tr><td>Context</td><td><code>Distill</code></td><td>Context deduplication and compression — cut window size by 40%+.</td></tr>
</table>
<div class="insight"><p>The strategic decision: use MCP and AGENTS.md today (both mature). Build lightweight abstractions around auth and observability where standards are still forming — migration from non-standard infrastructure compounds over time.</p></div>
</div>
</details>
<!-- PART 2 -->
<div class="part-header">
<div class="part-num-badge">Part 02 — 3 Chapters</div>
<div class="part-title">Context Engineering</div>
<p class="part-desc">The art of giving your agent exactly the right information, at the right time, without wasting tokens.</p>
</div>
<!-- CH04 -->
<details class="chapter" id="ch04">
<summary class="chapter-summary">
<span class="ch-num">Ch 04</span>
<span class="ch-info">
<span class="ch-title">Context Windows</span>