Architecture Decision Records for Agents

Building the AI Dark Factory — Issue #16 Preface

In the first installment of this series, it was emphasized that none of the frameworks discussed are original. The concepts originate from Dan Shapiro and Nate B. Jones, both of whom have dedicated extensive time to exploring these ideas. Dan Shapiro, CEO of Glowforge and a Wharton Research Fellow, coined the term "Dark Factory" in his blog post "The Five Levels: from Spicy Autocomplete to the Dark Factory."

Nate B. Jones, an AI strategist and creator of the popular YouTube channel, sparked this entire newsletter with his video "The 5 Levels of AI Coding (Why Most of You Won’t Make It Past Level 2)." This newsletter serves as a learning log for a Senior Software Engineer aiming to reach Level 5. The goal is to document the journey, including frameworks, tools, mindset shifts, and moments of realization about potential pitfalls.

Issue #15 introduced a production-grade CLAUDE.md, which referenced ADR-001 and ADR-002. This issue builds upon those ADRs, demonstrating a real-world failure mode that necessitates their existence. In a project's codebase, an agent tasked with optimizing the order creation endpoint made a locally reasonable change that violated a crucial invariant.

The significance of this incident lies in the fact that even with a comprehensive test suite, the violation may not be detected until it reaches production, embedded in a seemingly correct diff. This highlights the need for explicit documentation to prevent such issues.