{"id":"19-codebase","number":19,"slug":"agent-friendly-codebases","title":"Codebases agents can work in","short":"Agent-friendly codebases","module":"Quality, safety, teams","summary":"Bad codebases make bad agents, and agents can make a codebase bad fast: they copy whatever patterns they find, good or bad. Learn the principles that keep a codebase agent-friendly: make the shortest path the right path, deep modules, one way to do each thing, enforced architecture, simple code, and continuous cleanup.","voice":"Eric","scenes":[{"template":"title","chapter":"Intro","narration":"Matt Pocock puts it bluntly: bad codebases make bad agents. If you have a garbage codebase, you'll get garbage out of the agent working in it. This lesson is about the codebase side of agentic engineering.","params":{"kicker":"Lesson 19","module":"Module 5 · Quality, safety, teams","title":"Codebases agents can *work in*","subtitle":"Agents copy what they see. Make it worth copying.","bubble":"I learn from your code.","mood":"think"},"start":0.5,"dur":14.209,"words":[{"text":"Matt","s":0.8,"e":1.12},{"text":"Pocock","s":1.16,"e":1.6},{"text":"puts","s":1.68,"e":1.84},{"text":"it","s":1.92,"e":2},{"text":"bluntly:","s":2.08,"e":3.04},{"text":"bad","s":3.12,"e":3.36},{"text":"codebases","s":3.44,"e":4.16},{"text":"make","s":4.24,"e":4.48},{"text":"bad","s":4.64,"e":4.8},{"text":"agents.","s":4.88,"e":5.92},{"text":"If","s":6,"e":6.08},{"text":"you","s":6.12,"e":6.16},{"text":"have","s":6.24,"e":6.32},{"text":"a","s":6.4,"e":6.48},{"text":"garbage","s":6.56,"e":6.88},{"text":"codebase,","s":7,"e":7.68},{"text":"you'll","s":7.72,"e":7.84},{"text":"get","s":7.96,"e":8.08},{"text":"garbage","s":8.2,"e":8.56},{"text":"out","s":8.6,"e":8.64},{"text":"of","s":8.68,"e":8.72},{"text":"the","s":8.8,"e":8.88},{"text":"agent","s":9.04,"e":9.2},{"text":"working","s":9.28,"e":9.6},{"text":"in","s":9.64,"e":9.68},{"text":"it.","s":9.76,"e":10.4},{"text":"This","s":10.52,"e":10.64},{"text":"lesson","s":10.84,"e":11.04},{"text":"is","s":11.12,"e":11.2},{"text":"about","s":11.28,"e":11.44},{"text":"the","s":11.52,"e":11.6},{"text":"codebase","s":11.68,"e":12.16},{"text":"side","s":12.24,"e":12.48},{"text":"of","s":12.52,"e":12.56},{"text":"agentic","s":12.64,"e":12.96},{"text":"engineering.","s":13.04,"e":13.76}]},{"template":"quote","chapter":"Agents copy patterns","narration":"Why does the codebase matter so much? Because agents imitate it. OpenAI's harness team found their agent replicates patterns that already exist in the repository, even uneven or suboptimal ones. Over time, that inevitably leads to drift.","params":{"text":"Codex replicates patterns that already exist in the repository — even uneven or suboptimal ones. Over time, this inevitably leads to *drift*.","who":"Ryan Lopopolo","role":"OpenAI","src":"Harness engineering"},"start":14.709,"dur":17.303,"words":[{"text":"Why","s":15.009,"e":15.249},{"text":"does","s":15.329,"e":15.409},{"text":"the","s":15.489,"e":15.569},{"text":"codebase","s":15.649,"e":16.129},{"text":"matter","s":16.209,"e":16.449},{"text":"so","s":16.529,"e":16.689},{"text":"much?","s":16.769,"e":17.089},{"text":"Because","s":17.569,"e":17.889},{"text":"agents","s":17.969,"e":18.449},{"text":"imitate","s":18.529,"e":19.009},{"text":"it.","s":19.089,"e":19.249},{"text":"OpenAI's","s":19.729,"e":20.369},{"text":"harness","s":20.449,"e":20.769},{"text":"team","s":20.849,"e":21.089},{"text":"found","s":21.169,"e":21.409},{"text":"their","s":21.489,"e":21.569},{"text":"agent","s":21.649,"e":21.889},{"text":"replicates","s":22.049,"e":22.609},{"text":"patterns","s":22.689,"e":23.089},{"text":"that","s":23.209,"e":23.329},{"text":"already","s":23.529,"e":23.729},{"text":"exist","s":23.809,"e":24.209},{"text":"in","s":24.249,"e":24.289},{"text":"the","s":24.329,"e":24.369},{"text":"repository,","s":24.769,"e":25.569},{"text":"even","s":25.649,"e":25.889},{"text":"uneven","s":26.049,"e":26.609},{"text":"or","s":26.689,"e":26.769},{"text":"suboptimal","s":26.929,"e":27.489},{"text":"ones.","s":27.569,"e":28.169},{"text":"Over","s":28.449,"e":28.689},{"text":"time,","s":28.889,"e":29.329},{"text":"that","s":29.449,"e":29.569},{"text":"inevitably","s":29.729,"e":30.209},{"text":"leads","s":30.289,"e":30.529},{"text":"to","s":30.569,"e":30.609},{"text":"drift.","s":30.689,"e":31.409}]},{"template":"stat","chapter":"Decay is fast","narration":"And drift is fast. Mario Zechner says agents, making local decisions, pile up abstractions, duplication and backwards-compatibility shims. You get enterprise-grade complexity within two weeks, with just two humans and ten agents. Dex Horthy finds agents start to struggle in a codebase after three to six months.","params":{"items":[{"value":"2 weeks","label":"to “enterprise-grade complexity” with 2 humans + 10 agents","sub":"Mario Zechner","tone":"bad","at":"two weeks"},{"value":"3–6 mo","label":"until agents start to struggle in a fast-moving codebase","sub":"Dex Horthy","tone":"bad","at":"three to six"}]},"start":32.012,"dur":22.109,"words":[{"text":"And","s":32.312,"e":32.552},{"text":"drift","s":32.632,"e":32.952},{"text":"is","s":33.032,"e":33.272},{"text":"fast.","s":33.432,"e":34.272},{"text":"Mario","s":34.552,"e":34.872},{"text":"Zechner","s":34.952,"e":35.432},{"text":"says","s":35.592,"e":35.752},{"text":"agents,","s":35.912,"e":36.552},{"text":"making","s":36.712,"e":36.872},{"text":"local","s":36.952,"e":37.192},{"text":"decisions,","s":37.272,"e":38.072},{"text":"pile","s":38.232,"e":38.392},{"text":"up","s":38.472,"e":38.552},{"text":"abstractions,","s":38.672,"e":39.592},{"text":"duplication","s":39.672,"e":40.312},{"text":"and","s":40.472,"e":40.552},{"text":"backwards-compatibility","s":40.632,"e":41.832},{"text":"shims.","s":41.912,"e":42.592},{"text":"You","s":42.872,"e":42.952},{"text":"get","s":43.072,"e":43.192},{"text":"enterprise-grade","s":43.472,"e":43.992},{"text":"complexity","s":44.072,"e":44.632},{"text":"within","s":44.832,"e":45.032},{"text":"two","s":45.152,"e":45.272},{"text":"weeks,","s":45.352,"e":45.912},{"text":"with","s":45.992,"e":46.072},{"text":"just","s":46.152,"e":46.312},{"text":"two","s":46.392,"e":46.552},{"text":"humans","s":46.632,"e":47.032},{"text":"and","s":47.112,"e":47.272},{"text":"ten","s":47.392,"e":47.512},{"text":"agents.","s":47.752,"e":48.312},{"text":"Dex","s":48.632,"e":48.872},{"text":"Horthy","s":48.952,"e":49.352},{"text":"finds","s":49.432,"e":49.752},{"text":"agents","s":49.952,"e":50.152},{"text":"start","s":50.272,"e":50.392},{"text":"to","s":50.472,"e":50.552},{"text":"struggle","s":50.672,"e":50.952},{"text":"in","s":51.032,"e":51.112},{"text":"a","s":51.152,"e":51.192},{"text":"codebase","s":51.352,"e":51.752},{"text":"after","s":51.952,"e":52.152},{"text":"three","s":52.232,"e":52.312},{"text":"to","s":52.392,"e":52.552},{"text":"six","s":52.672,"e":52.792},{"text":"months.","s":52.872,"e":53.512}]},{"template":"statement","chapter":"Why it happens","narration":"Kent Beck names the mechanism. Agents are prone to decisions that cause disruption at a distance. They don't reduce coupling or increase cohesion unless you tell them to. Each change is locally reasonable, and together they make a mess.","params":{"text":"Agents don't reduce coupling or increase cohesion *unless you tell them to*.","sub":"Kent Beck: “disruption at a distance”","art":"warn","tone":"bad","sync":false},"start":54.121,"dur":16.597,"words":[{"text":"Kent","s":54.421,"e":54.741},{"text":"Beck","s":54.821,"e":55.061},{"text":"names","s":55.141,"e":55.461},{"text":"the","s":55.501,"e":55.541},{"text":"mechanism.","s":55.621,"e":56.501},{"text":"Agents","s":56.821,"e":57.141},{"text":"are","s":57.221,"e":57.301},{"text":"prone","s":57.381,"e":57.621},{"text":"to","s":57.701,"e":57.781},{"text":"decisions","s":57.901,"e":58.421},{"text":"that","s":58.501,"e":58.581},{"text":"cause","s":58.661,"e":58.901},{"text":"disruption","s":58.981,"e":59.621},{"text":"at","s":59.701,"e":59.781},{"text":"a","s":59.861,"e":59.941},{"text":"distance.","s":60.021,"e":60.821},{"text":"They","s":61.061,"e":61.221},{"text":"don't","s":61.301,"e":61.461},{"text":"reduce","s":61.661,"e":61.861},{"text":"coupling","s":61.941,"e":62.421},{"text":"or","s":62.501,"e":62.661},{"text":"increase","s":62.861,"e":63.061},{"text":"cohesion","s":63.141,"e":63.781},{"text":"unless","s":63.861,"e":64.181},{"text":"you","s":64.261,"e":64.341},{"text":"tell","s":64.421,"e":64.661},{"text":"them","s":64.781,"e":64.901},{"text":"to.","s":65.021,"e":65.421},{"text":"Each","s":65.701,"e":65.941},{"text":"change","s":66.021,"e":66.341},{"text":"is","s":66.421,"e":66.581},{"text":"locally","s":66.741,"e":67.141},{"text":"reasonable,","s":67.221,"e":67.941},{"text":"and","s":68.021,"e":68.101},{"text":"together","s":68.181,"e":68.581},{"text":"they","s":68.901,"e":68.981},{"text":"make","s":69.061,"e":69.141},{"text":"a","s":69.221,"e":69.301},{"text":"mess.","s":69.381,"e":70.101}]},{"template":"statement","chapter":"The shortest path","narration":"The first principle comes from Lauren Tan: make the shortest path the best path. Agents love shortcuts. So structure your code so that the lazy route is the correct one. Put a feature's code together in one place, and keep one obvious way to do each thing.","params":{"text":"Make the *shortest path* the right path.","sub":"Agents take shortcuts. Make the lazy route the correct one. — Lauren Tan","art":"target","tone":"good"},"start":70.718,"dur":17.877,"words":[{"text":"The","s":71.018,"e":71.178},{"text":"first","s":71.298,"e":71.418},{"text":"principle","s":71.498,"e":71.978},{"text":"comes","s":72.058,"e":72.298},{"text":"from","s":72.378,"e":72.458},{"text":"Lauren","s":72.538,"e":72.858},{"text":"Tan:","s":72.938,"e":73.818},{"text":"make","s":73.898,"e":74.058},{"text":"the","s":74.098,"e":74.138},{"text":"shortest","s":74.298,"e":74.618},{"text":"path","s":74.698,"e":75.098},{"text":"the","s":75.338,"e":75.418},{"text":"best","s":75.498,"e":75.818},{"text":"path.","s":76.018,"e":76.298},{"text":"Agents","s":76.938,"e":77.418},{"text":"love","s":77.658,"e":77.898},{"text":"shortcuts.","s":77.978,"e":78.618},{"text":"So","s":79.098,"e":79.258},{"text":"structure","s":79.418,"e":79.818},{"text":"your","s":79.898,"e":79.978},{"text":"code","s":80.058,"e":80.378},{"text":"so","s":80.458,"e":80.538},{"text":"that","s":80.618,"e":80.698},{"text":"the","s":80.738,"e":80.778},{"text":"lazy","s":80.858,"e":81.178},{"text":"route","s":81.258,"e":81.498},{"text":"is","s":81.578,"e":81.658},{"text":"the","s":81.738,"e":81.778},{"text":"correct","s":81.818,"e":82.138},{"text":"one.","s":82.218,"e":82.458},{"text":"Put","s":82.938,"e":83.018},{"text":"a","s":83.058,"e":83.098},{"text":"feature's","s":83.178,"e":83.498},{"text":"code","s":83.578,"e":83.738},{"text":"together","s":83.818,"e":84.138},{"text":"in","s":84.218,"e":84.378},{"text":"one","s":84.458,"e":84.618},{"text":"place,","s":84.698,"e":85.178},{"text":"and","s":85.258,"e":85.338},{"text":"keep","s":85.458,"e":85.578},{"text":"one","s":85.738,"e":85.978},{"text":"obvious","s":86.058,"e":86.538},{"text":"way","s":86.618,"e":86.778},{"text":"to","s":86.858,"e":86.938},{"text":"do","s":87.058,"e":87.178},{"text":"each","s":87.298,"e":87.418},{"text":"thing.","s":87.498,"e":87.978}]},{"template":"compare","chapter":"Deep modules","narration":"Second, prefer deep modules: a small interface hiding a lot of functionality. Left alone, agents tend to produce many tiny, shallow modules that are hard to navigate. Matt Pocock's approach: design the module interfaces yourself, and delegate the implementations, treating each module as a gray box with tests at its boundary.","params":{"left":{"title":"Shallow modules","items":["Dozens of tiny files","Logic leaks across boundaries","Hard to test as a unit"],"at":"Left alone"},"right":{"title":"Deep modules","items":["Small interface, lots inside","You design the interface","Tests at the boundary"],"at":"prefer deep modules"}},"start":88.595,"dur":23.076,"words":[{"text":"Second,","s":88.895,"e":89.375},{"text":"prefer","s":89.775,"e":90.142},{"text":"deep","s":90.175,"e":90.515},{"text":"modules:","s":90.575,"e":91.535},{"text":"a","s":91.615,"e":91.695},{"text":"small","s":91.775,"e":92.015},{"text":"interface","s":92.095,"e":92.655},{"text":"hiding","s":92.735,"e":93.055},{"text":"a","s":93.135,"e":93.255},{"text":"lot","s":93.375,"e":93.535},{"text":"of","s":93.615,"e":93.695},{"text":"functionality.","s":93.855,"e":95.055},{"text":"Left","s":95.175,"e":95.295},{"text":"alone,","s":95.535,"e":95.935},{"text":"agents","s":96.135,"e":96.335},{"text":"tend","s":96.415,"e":96.575},{"text":"to","s":96.615,"e":96.655},{"text":"produce","s":96.735,"e":97.055},{"text":"many","s":97.215,"e":97.535},{"text":"tiny,","s":97.775,"e":98.175},{"text":"shallow","s":98.255,"e":98.495},{"text":"modules","s":98.575,"e":99.055},{"text":"that","s":99.135,"e":99.215},{"text":"are","s":99.295,"e":99.375},{"text":"hard","s":99.495,"e":99.615},{"text":"to","s":99.655,"e":99.695},{"text":"navigate.","s":99.775,"e":100.735},{"text":"Matt","s":101.215,"e":101.295},{"text":"Pocock's","s":101.415,"e":101.908},{"text":"approach:","s":102.015,"e":103.015},{"text":"design","s":103.215,"e":103.255},{"text":"the","s":103.295,"e":103.375},{"text":"module","s":103.695,"e":103.775},{"text":"interfaces","s":104.335,"e":104.415},{"text":"yourself,","s":104.655,"e":105.215},{"text":"and","s":105.295,"e":105.375},{"text":"delegate","s":105.775,"e":105.815},{"text":"the","s":105.855,"e":105.935},{"text":"implementations,","s":106.335,"e":107.255},{"text":"treating","s":107.295,"e":107.615},{"text":"each","s":107.775,"e":107.855},{"text":"module","s":108.255,"e":108.335},{"text":"as","s":108.415,"e":108.495},{"text":"a","s":108.575,"e":108.695},{"text":"gray","s":108.815,"e":108.895},{"text":"box","s":109.295,"e":109.415},{"text":"with","s":109.535,"e":109.775},{"text":"tests","s":110.015,"e":110.055},{"text":"at","s":110.095,"e":110.175},{"text":"its","s":110.255,"e":110.335},{"text":"boundary.","s":110.735,"e":111.055}]},{"template":"list","chapter":"Sameness","narration":"Third, sameness. Ryan Lopopolo's goal is to make the tokens needed for the job easy to predict, by making things the same as much as possible. One ORM, one language, one style of CI script, one way to do each shared thing. And with agents, finishing migrations is cheap, so don't leave two ways around for months.","params":{"title":"One way to do each thing","items":[{"text":"One ORM, one language, one CI style","at":"One ORM"},{"text":"One pattern per kind of change","sub":"endpoints, jobs, migrations","at":"shared thing"},{"text":"Finish migrations","sub":"agents make the long tail cheap","at":"migrations"}]},"start":111.671,"dur":22.658,"words":[{"text":"Third,","s":111.971,"e":112.771},{"text":"sameness.","s":112.931,"e":113.891},{"text":"Ryan","s":114.211,"e":114.451},{"text":"Lopopolo's","s":114.531,"e":115.091},{"text":"goal","s":115.171,"e":115.411},{"text":"is","s":115.491,"e":115.651},{"text":"to","s":115.691,"e":115.731},{"text":"make","s":115.811,"e":115.971},{"text":"the","s":116.011,"e":116.051},{"text":"tokens","s":116.131,"e":116.531},{"text":"needed","s":116.611,"e":116.851},{"text":"for","s":116.891,"e":116.931},{"text":"the","s":117.011,"e":117.091},{"text":"job","s":117.171,"e":117.491},{"text":"easy","s":117.571,"e":117.811},{"text":"to","s":117.891,"e":117.971},{"text":"predict,","s":118.051,"e":118.771},{"text":"by","s":118.851,"e":118.931},{"text":"making","s":119.091,"e":119.251},{"text":"things","s":119.371,"e":119.491},{"text":"the","s":119.571,"e":119.731},{"text":"same","s":119.931,"e":120.131},{"text":"as","s":120.211,"e":120.291},{"text":"much","s":120.451,"e":120.611},{"text":"as","s":120.691,"e":120.771},{"text":"possible.","s":120.851,"e":121.891},{"text":"One","s":121.971,"e":122.051},{"text":"ORM,","s":122.131,"e":123.011},{"text":"one","s":123.091,"e":123.171},{"text":"language,","s":123.251,"e":124.051},{"text":"one","s":124.131,"e":124.211},{"text":"style","s":124.291,"e":124.611},{"text":"of","s":124.651,"e":124.691},{"text":"CI","s":124.771,"e":125.091},{"text":"script,","s":125.251,"e":125.811},{"text":"one","s":125.891,"e":126.051},{"text":"way","s":126.131,"e":126.291},{"text":"to","s":126.371,"e":126.451},{"text":"do","s":126.571,"e":126.691},{"text":"each","s":126.811,"e":126.931},{"text":"shared","s":127.091,"e":127.411},{"text":"thing.","s":127.491,"e":128.371},{"text":"And","s":128.411,"e":128.451},{"text":"with","s":128.531,"e":128.611},{"text":"agents,","s":128.691,"e":129.411},{"text":"finishing","s":129.491,"e":129.731},{"text":"migrations","s":129.811,"e":130.371},{"text":"is","s":130.451,"e":130.531},{"text":"cheap,","s":130.611,"e":131.171},{"text":"so","s":131.251,"e":131.491},{"text":"don't","s":131.531,"e":131.731},{"text":"leave","s":131.851,"e":131.971},{"text":"two","s":132.051,"e":132.131},{"text":"ways","s":132.211,"e":132.451},{"text":"around","s":132.611,"e":132.771},{"text":"for","s":132.891,"e":133.011},{"text":"months.","s":133.211,"e":133.731}]},{"template":"stack","chapter":"Enforced architecture","narration":"Fourth, enforce your architecture. OpenAI's team gives every domain the same fixed layers, from types, to config, to repositories, services, runtime and UI, with dependency directions checked by custom linters. They note that this kind of architecture is usually postponed until you have hundreds of engineers. With agents, it's an early prerequisite.","params":{"title":"Fixed layers, checked by linters","sub":"Each layer may depend only on the layers below it.","layers":[{"label":"Types","tone":"ink","at":"types"},{"label":"Config","tone":"paper","at":"config"},{"label":"Repo","tone":"paper","at":"repositories"},{"label":"Service","tone":"soft","at":"services"},{"label":"Runtime","tone":"soft","at":"runtime"},{"label":"UI","tone":"agent","at":"UI"}]},"start":134.329,"dur":24.512,"words":[{"text":"Fourth,","s":134.629,"e":135.109},{"text":"enforce","s":135.509,"e":136.069},{"text":"your","s":136.149,"e":136.309},{"text":"architecture.","s":136.669,"e":137.349},{"text":"OpenAI's","s":137.669,"e":138.389},{"text":"team","s":138.549,"e":138.709},{"text":"gives","s":138.816,"e":139.029},{"text":"every","s":139.109,"e":139.349},{"text":"domain","s":139.549,"e":139.749},{"text":"the","s":139.829,"e":139.989},{"text":"same","s":140.189,"e":140.389},{"text":"fixed","s":140.469,"e":140.709},{"text":"layers,","s":140.789,"e":141.429},{"text":"from","s":141.549,"e":141.669},{"text":"types,","s":141.909,"e":142.229},{"text":"to","s":142.269,"e":142.309},{"text":"config,","s":142.389,"e":143.109},{"text":"to","s":143.149,"e":143.189},{"text":"repositories,","s":143.669,"e":144.309},{"text":"services,","s":144.389,"e":145.269},{"text":"runtime","s":145.549,"e":145.829},{"text":"and","s":145.909,"e":146.069},{"text":"UI,","s":146.149,"e":146.949},{"text":"with","s":147.029,"e":147.109},{"text":"dependency","s":147.389,"e":147.669},{"text":"directions","s":147.749,"e":148.309},{"text":"checked","s":148.389,"e":148.629},{"text":"by","s":148.709,"e":148.789},{"text":"custom","s":148.869,"e":149.189},{"text":"linters.","s":149.309,"e":150.309},{"text":"They","s":150.389,"e":150.469},{"text":"note","s":150.549,"e":150.629},{"text":"that","s":150.709,"e":150.789},{"text":"this","s":150.869,"e":150.949},{"text":"kind","s":151.029,"e":151.109},{"text":"of","s":151.189,"e":151.269},{"text":"architecture","s":151.589,"e":151.909},{"text":"is","s":151.989,"e":152.149},{"text":"usually","s":152.229,"e":152.629},{"text":"postponed","s":152.789,"e":153.269},{"text":"until","s":153.429,"e":153.589},{"text":"you","s":153.629,"e":153.669},{"text":"have","s":153.749,"e":153.989},{"text":"hundreds","s":154.029,"e":154.389},{"text":"of","s":154.429,"e":154.469},{"text":"engineers.","s":154.549,"e":155.589},{"text":"With","s":155.669,"e":155.749},{"text":"agents,","s":155.829,"e":156.549},{"text":"it's","s":156.589,"e":156.709},{"text":"an","s":156.789,"e":156.869},{"text":"early","s":157.029,"e":157.189},{"text":"prerequisite.","s":157.269,"e":158.229}]},{"template":"quote","chapter":"Simple code","narration":"Fifth, keep code simple. Armin Ronacher's experience: simple code significantly outperforms complex code in agentic contexts. Ask for the dumbest thing that will work. Prefer plain functions with descriptive names over clever class hierarchies, and generating a few lines over adding a dependency.","params":{"text":"Simple code significantly *outperforms* complex code in agentic contexts.","who":"Armin Ronacher","role":"creator of Flask","src":"Agentic Coding Recommendations"},"start":158.841,"dur":21.143,"words":[{"text":"Fifth,","s":159.141,"e":159.621},{"text":"keep","s":160.021,"e":160.261},{"text":"code","s":160.341,"e":160.661},{"text":"simple.","s":160.821,"e":161.301},{"text":"Armin","s":161.941,"e":162.261},{"text":"Ronacher's","s":162.341,"e":162.741},{"text":"experience:","s":163.061,"e":163.941},{"text":"simple","s":164.021,"e":164.341},{"text":"code","s":164.421,"e":164.741},{"text":"significantly","s":164.821,"e":165.621},{"text":"outperforms","s":165.701,"e":166.341},{"text":"complex","s":166.421,"e":166.901},{"text":"code","s":166.981,"e":167.221},{"text":"in","s":167.301,"e":167.381},{"text":"agentic","s":167.461,"e":167.781},{"text":"contexts.","s":167.861,"e":168.781},{"text":"Ask","s":169.061,"e":169.301},{"text":"for","s":169.381,"e":169.461},{"text":"the","s":169.501,"e":169.541},{"text":"dumbest","s":169.781,"e":170.101},{"text":"thing","s":170.181,"e":170.261},{"text":"that","s":170.341,"e":170.421},{"text":"will","s":170.501,"e":170.581},{"text":"work.","s":170.661,"e":170.981},{"text":"Prefer","s":171.381,"e":171.701},{"text":"plain","s":171.781,"e":172.101},{"text":"functions","s":172.181,"e":172.581},{"text":"with","s":172.661,"e":172.821},{"text":"descriptive","s":172.901,"e":173.381},{"text":"names","s":173.461,"e":173.861},{"text":"over","s":173.941,"e":174.101},{"text":"clever","s":174.261,"e":174.581},{"text":"class","s":174.741,"e":174.901},{"text":"hierarchies,","s":174.981,"e":176.021},{"text":"and","s":176.141,"e":176.261},{"text":"generating","s":176.501,"e":176.901},{"text":"a","s":176.981,"e":177.061},{"text":"few","s":177.141,"e":177.301},{"text":"lines","s":177.381,"e":177.781},{"text":"over","s":177.861,"e":178.021},{"text":"adding","s":178.101,"e":178.341},{"text":"a","s":178.368,"e":178.394},{"text":"dependency.","s":178.421,"e":179.381}]},{"template":"list","chapter":"Strong feedback","narration":"And give the agent strong feedback built into the code itself. Matt Pocock's wish list: more tests, higher quality tests, non-flaky tests, and above all, types, types, types. Thorsten Ball adds that over time, your codebase should hold more and more of the how-to knowledge, so your prompts can get shorter.","params":{"title":"Feedback built into the code","items":[{"text":"Types, types, types","at":"types, types"},{"text":"Fast, non-flaky tests","at":"non-flaky"},{"text":"How-to knowledge lives in the repo","sub":"so prompts get shorter","at":"how-to"}]},"start":179.984,"dur":22.423,"words":[{"text":"And","s":180.284,"e":180.444},{"text":"give","s":180.524,"e":180.604},{"text":"the","s":180.684,"e":180.764},{"text":"agent","s":180.844,"e":181.164},{"text":"strong","s":181.244,"e":181.644},{"text":"feedback","s":181.804,"e":182.284},{"text":"built","s":182.444,"e":182.684},{"text":"into","s":182.764,"e":182.844},{"text":"the","s":182.924,"e":183.004},{"text":"code","s":183.084,"e":183.244},{"text":"itself.","s":183.364,"e":184.324},{"text":"Matt","s":184.764,"e":184.924},{"text":"Pocock's","s":185.004,"e":185.484},{"text":"wish","s":185.604,"e":185.724},{"text":"list:","s":185.804,"e":186.604},{"text":"more","s":186.684,"e":186.844},{"text":"tests,","s":186.924,"e":187.724},{"text":"higher","s":187.844,"e":187.964},{"text":"quality","s":188.044,"e":188.444},{"text":"tests,","s":188.524,"e":189.324},{"text":"non-flaky","s":189.404,"e":190.124},{"text":"tests,","s":190.204,"e":190.844},{"text":"and","s":190.884,"e":190.924},{"text":"above","s":191.084,"e":191.324},{"text":"all,","s":191.404,"e":191.644},{"text":"types,","s":191.884,"e":192.524},{"text":"types,","s":192.764,"e":193.164},{"text":"types.","s":193.404,"e":193.724},{"text":"Thorsten","s":194.284,"e":194.684},{"text":"Ball","s":194.764,"e":195.004},{"text":"adds","s":195.084,"e":195.324},{"text":"that","s":195.404,"e":195.564},{"text":"over","s":195.644,"e":195.884},{"text":"time,","s":195.964,"e":196.524},{"text":"your","s":196.604,"e":196.684},{"text":"codebase","s":196.764,"e":197.164},{"text":"should","s":197.244,"e":197.324},{"text":"hold","s":197.404,"e":197.564},{"text":"more","s":197.724,"e":197.964},{"text":"and","s":198.044,"e":198.124},{"text":"more","s":198.284,"e":198.444},{"text":"of","s":198.524,"e":198.604},{"text":"the","s":198.684,"e":198.764},{"text":"how-to","s":198.844,"e":199.324},{"text":"knowledge,","s":199.524,"e":200.044},{"text":"so","s":200.124,"e":200.204},{"text":"your","s":200.284,"e":200.364},{"text":"prompts","s":200.444,"e":200.764},{"text":"can","s":200.844,"e":200.924},{"text":"get","s":201.004,"e":201.084},{"text":"shorter.","s":201.164,"e":201.804}]},{"template":"flow","chapter":"Clean continuously","narration":"Finally, clean continuously. OpenAI's team first spent every Friday, a fifth of the week, cleaning up AI slop by hand. It didn't scale. So they encoded golden principles as rules, and scheduled background agents that scan for deviations and open small refactoring pull requests. Garbage collection for code.","params":{"nodes":[{"label":"Fridays: manual cleanup","sub":"20% of the week, didn't scale","kind":"warn","at":"every Friday"},{"label":"Golden principles","sub":"rules, written down","kind":"doc","at":"golden principles"},{"label":"Background agents","sub":"scan for deviations","kind":"agent","at":"scan"},{"label":"Small refactor PRs","sub":"garbage collection","kind":"check","at":"refactoring"}]},"start":202.407,"dur":22.736,"words":[{"text":"Finally,","s":202.707,"e":203.507},{"text":"clean","s":203.587,"e":203.907},{"text":"continuously.","s":204.067,"e":205.267},{"text":"OpenAI's","s":205.587,"e":206.227},{"text":"team","s":206.307,"e":206.627},{"text":"first","s":206.707,"e":206.947},{"text":"spent","s":207.107,"e":207.267},{"text":"every","s":207.427,"e":207.667},{"text":"Friday,","s":207.747,"e":208.467},{"text":"a","s":208.547,"e":208.627},{"text":"fifth","s":208.68,"e":208.787},{"text":"of","s":208.867,"e":208.947},{"text":"the","s":208.987,"e":209.027},{"text":"week,","s":209.107,"e":209.667},{"text":"cleaning","s":209.787,"e":209.987},{"text":"up","s":210.067,"e":210.227},{"text":"AI","s":210.307,"e":210.627},{"text":"slop","s":210.707,"e":211.027},{"text":"by","s":211.107,"e":211.267},{"text":"hand.","s":211.347,"e":212.147},{"text":"It","s":212.227,"e":212.307},{"text":"didn't","s":212.387,"e":212.547},{"text":"scale.","s":212.627,"e":213.587},{"text":"So","s":213.707,"e":213.827},{"text":"they","s":213.987,"e":214.067},{"text":"encoded","s":214.147,"e":214.627},{"text":"golden","s":214.707,"e":215.027},{"text":"principles","s":215.107,"e":215.587},{"text":"as","s":215.667,"e":215.827},{"text":"rules,","s":215.907,"e":216.547},{"text":"and","s":216.587,"e":216.627},{"text":"scheduled","s":216.707,"e":217.187},{"text":"background","s":217.427,"e":217.667},{"text":"agents","s":217.747,"e":218.067},{"text":"that","s":218.147,"e":218.227},{"text":"scan","s":218.387,"e":218.627},{"text":"for","s":218.707,"e":218.787},{"text":"deviations","s":218.867,"e":219.587},{"text":"and","s":219.827,"e":219.907},{"text":"open","s":219.987,"e":220.227},{"text":"small","s":220.307,"e":220.627},{"text":"refactoring","s":220.707,"e":221.347},{"text":"pull","s":221.427,"e":221.587},{"text":"requests.","s":221.867,"e":222.427},{"text":"Garbage","s":222.707,"e":223.107},{"text":"collection","s":223.187,"e":223.587},{"text":"for","s":223.667,"e":223.747},{"text":"code.","s":223.827,"e":224.547}]},{"template":"quiz","chapter":"Quick check","narration":"Quick check. Your codebase has three different ways to query the database, and agents keep mixing them. What's the best fix? Tap your answer.","params":{"q":"Three ways to query the database; agents keep mixing them. Best fix?","options":["Mention the preferred one in every prompt","Pick one, migrate the rest with agents, and ban the others with a lint rule","Add a fourth, cleaner way","Accept it, everything still works"],"answer":1,"explain":"One way to do each thing, enforced by tooling, is something agents can't get wrong."},"start":225.143,"dur":14.591,"words":[{"text":"Quick","s":225.443,"e":225.683},{"text":"check.","s":225.763,"e":226.083},{"text":"Your","s":226.563,"e":226.723},{"text":"codebase","s":226.843,"e":227.203},{"text":"has","s":227.363,"e":227.523},{"text":"three","s":227.643,"e":227.763},{"text":"different","s":227.843,"e":228.083},{"text":"ways","s":228.163,"e":228.403},{"text":"to","s":228.483,"e":228.563},{"text":"query","s":228.643,"e":228.883},{"text":"the","s":228.923,"e":228.963},{"text":"database,","s":229.043,"e":229.843},{"text":"and","s":229.963,"e":230.083},{"text":"agents","s":230.163,"e":230.563},{"text":"keep","s":230.643,"e":230.803},{"text":"mixing","s":230.883,"e":231.283},{"text":"them.","s":231.363,"e":232.003},{"text":"What's","s":232.083,"e":232.203},{"text":"the","s":232.243,"e":232.283},{"text":"best","s":232.323,"e":232.483},{"text":"fix?","s":232.563,"e":233.203},{"text":"Tap","s":233.443,"e":233.683},{"text":"your","s":233.763,"e":233.843},{"text":"answer.","s":234.043,"e":234.563}]},{"template":"exercise","chapter":"Try it","narration":"Audit your codebase from an agent's point of view. This prompt finds the places most likely to mislead an agent, and suggests a fix for each.","params":{"title":"Try it with your agent","intro":"Audit your repo for agent-friendliness:","prompt":"Audit this codebase from an agent's point of view. Find: several\nways of doing the same thing, shallow or tangled modules, weak types,\nflaky or slow tests, and patterns an agent would copy badly.\nRank the top 5 by how much they'd mislead an agent, with a fix each."},"start":239.734,"dur":9.544,"words":[{"text":"Audit","s":240.034,"e":240.354},{"text":"your","s":240.434,"e":240.514},{"text":"codebase","s":240.594,"e":241.074},{"text":"from","s":241.154,"e":241.234},{"text":"an","s":241.354,"e":241.474},{"text":"agent's","s":241.634,"e":241.874},{"text":"point","s":241.954,"e":242.114},{"text":"of","s":242.154,"e":242.194},{"text":"view.","s":242.314,"e":243.074},{"text":"This","s":243.194,"e":243.314},{"text":"prompt","s":243.394,"e":243.714},{"text":"finds","s":243.794,"e":244.034},{"text":"the","s":244.114,"e":244.194},{"text":"places","s":244.434,"e":244.674},{"text":"most","s":244.834,"e":244.994},{"text":"likely","s":245.074,"e":245.394},{"text":"to","s":245.434,"e":245.474},{"text":"mislead","s":245.554,"e":246.034},{"text":"an","s":246.074,"e":246.114},{"text":"agent,","s":246.194,"e":246.754},{"text":"and","s":246.834,"e":246.914},{"text":"suggests","s":247.114,"e":247.394},{"text":"a","s":247.474,"e":247.554},{"text":"fix","s":247.634,"e":247.874},{"text":"for","s":247.954,"e":248.034},{"text":"each.","s":248.114,"e":248.674}]},{"template":"recap","chapter":"Recap","narration":"Recap. Agents copy what they see, so decay is fast. Make the shortest path the right path. Deep modules, one way to do each thing, enforced architecture, simple code and strong feedback. And clean continuously. Next: how to measure whether your agents are actually doing well, with evals.","params":{"items":["Agents *copy* what they see","Shortest path = right path","Deep modules · sameness · enforced layers","Simple code; clean continuously"],"next":"Evals: measure, don't vibe","next_at":"Next"},"start":249.278,"dur":24.574,"words":[{"text":"Recap.","s":249.578,"e":250.138},{"text":"Agents","s":250.218,"e":251.098},{"text":"copy","s":251.178,"e":251.498},{"text":"what","s":251.578,"e":251.658},{"text":"they","s":251.738,"e":251.898},{"text":"see,","s":252.058,"e":252.538},{"text":"so","s":252.618,"e":252.778},{"text":"decay","s":252.938,"e":253.418},{"text":"is","s":253.498,"e":253.658},{"text":"fast.","s":253.738,"e":254.618},{"text":"Make","s":254.698,"e":254.778},{"text":"the","s":254.858,"e":254.938},{"text":"shortest","s":255.018,"e":255.418},{"text":"path","s":255.498,"e":255.818},{"text":"the","s":255.978,"e":256.058},{"text":"right","s":256.218,"e":256.378},{"text":"path.","s":256.458,"e":257.138},{"text":"Deep","s":257.418,"e":257.658},{"text":"modules,","s":257.738,"e":258.698},{"text":"one","s":258.778,"e":258.938},{"text":"way","s":259.018,"e":259.178},{"text":"to","s":259.258,"e":259.338},{"text":"do","s":259.418,"e":259.498},{"text":"each","s":259.658,"e":259.818},{"text":"thing,","s":259.898,"e":260.618},{"text":"enforced","s":260.738,"e":261.098},{"text":"architecture,","s":261.178,"e":262.298},{"text":"simple","s":262.378,"e":262.698},{"text":"code","s":262.778,"e":263.098},{"text":"and","s":263.178,"e":263.338},{"text":"strong","s":263.418,"e":263.738},{"text":"feedback.","s":263.898,"e":264.458},{"text":"And","s":264.858,"e":265.178},{"text":"clean","s":265.418,"e":265.738},{"text":"continuously.","s":265.818,"e":267.258},{"text":"Next:","s":267.818,"e":268.258},{"text":"how","s":268.298,"e":268.378},{"text":"to","s":268.458,"e":268.538},{"text":"measure","s":268.778,"e":268.858},{"text":"whether","s":269.018,"e":269.098},{"text":"your","s":269.178,"e":269.258},{"text":"agents","s":269.578,"e":269.658},{"text":"are","s":269.738,"e":269.818},{"text":"actually","s":270.218,"e":270.298},{"text":"doing","s":270.538,"e":270.618},{"text":"well,","s":270.858,"e":271.258},{"text":"with","s":271.338,"e":271.418},{"text":"evals.","s":271.898,"e":272.298}]}],"total":274.252,"audio":"/audio/19-codebase.mp3"}