❌

Normal view

There are new articles available, click to refresh the page.
Before yesterdayBlunderGOAT

Development Driven Testing

6 April 2026 at 20:17
The last two developers I onboarded both asked about test driven development. They were shocked when I said TDD is unnecessary for most work. I've tried writing tests first, but over the past 25 years I've found it's very rarely the best approach. And have watched developers on my team struggle with productivity and extra cognitive load trying to make it work. **Development should drive the tests, not the other way around.** TDD advocates have told me that difficulty is the process working as intended. That our red-green-refactor loops were too large, and we should be writing a single tiny test for just the next few lines of code. But if the change is that small, static analysis or existing tests might catch that. Beller et al. observed 2,443 developers over 2.5 years and found that only 2.2% of sessions contained strict TDD patterns. If almost nobody does "true TDD," the problem might be the methodology, not the developers. And if what most developers actually practice looks nothing like TDD, then calling it TDD is just lending the methodology's credibility to a completely different workflow. **Just because you didn't work test-first doesn't mean you have to work test-never.** Others will argue TDD's real value is design, not testing. That writing the test first forces better architecture. From my experience, getting better at planning is more valuable than forcing design through a testing framework. On a healthcare SaaS platform I've worked on for 13 years, the best architecture decisions came from understanding the domain and planning the approach, not from writing a test and letting it push me toward a shape. Plan before you code, update the plan as you learn, and sharpen it as you go. That's a skill worth developing. Writing throwaway tests to arrive at the same design decisions is the long way around. There are moments where writing the test first does make sense, when the behaviour is already fully understood and you're codifying a known expectation. But that's a small subset of real development work, and it doesn't require TDD as a philosophy. ## TDD debate This argument has been going on for over a decade. Here's where it stands. **"TDD causes design damage."** DHH (creator of Ruby on Rails) argued in 2014 that designing code for testability rather than for the problem domain produces worse architecture. TDD advocates respond that this is a mocking problem, not a TDD problem. Kent Beck himself said he mocks almost nothing. **"Most unit testing is waste."** Jim Coplien argued in 2014 that unit tests mostly cover cases that never occur in practice, and only have real value when testing algorithmic logic. TDD advocates respond that tests catch regressions you can't predict. Coplien's counter: integration and system tests do that better. **"You're doing TDD wrong."** The most common defence. If it's not working, your loops are too large or you're over-isolating. But the Beller study found only 2.2% of developers follow strict TDD. If almost nobody does it correctly, that's worth paying attention to. **"TDD is a design tool, not a testing tool."** The strongest defence. Writing the test first makes you think about the interface before you write the code. But Kent Beck said he tests "as little as possible to reach a given level of confidence." Martin Fowler said self-testing code matters more than whether you wrote the test first. **Even TDD's creators have softened.** In the 2014 "Is TDD Dead?" conversations, Beck framed testing decisions as trade-offs involving skill, scope, lifespan, and coupling rather than as a universal discipline. Fowler drew a line between self-testing code and TDD, saying TDD is one path to self-testing code but not the only one. They concluded closer to "test what matters, when it matters" than to strict test-first. In my view, that's development driven testing. ## What the research shows The pattern across TDD research is consistent: the test-first part, the thing that actually defines TDD, has little to no measurable effect. **Erdogmus, Morisio, and Torchiano** ran a controlled experiment and found that writing more tests correlated with higher productivity regardless of whether tests were written first or last. The benefit came from testing, not from sequencing. **Fucci et al. (2017)** studied 39 professionals. The order you write tests and code in? Didn't matter. What mattered was working in small cycles. The test-first part had no effect on quality or productivity. **Rafique and Miőić (2013)** looked across 27 studies. TDD showed a small quality benefit, and that's worth acknowledging, it's the strongest thing the research has in TDD's favour. But there was no productivity benefit. When they split by setting, productivity went up 19% in university studies but dropped 22% in industry. The more the work looked like real development, the worse TDD performed on productivity. **Bissi et al. (2016)** reviewed studies from 1999 to 2014. About 44% showed lower productivity with TDD compared to writing tests after. Professional teams consistently did worse. **Tosun et al. (2017)** tested 24 professionals on tasks of varying complexity. TDD helped on simple tasks. On complex ones, productivity dropped. The more the work looked like real development, the worse TDD performed. **Ghafari et al. (2020)** asked why TDD research is so inconclusive and identified five problems: studies define TDD differently, participants are often TDD newcomers, experiments focus on greenfield code, no one tests TDD on existing codebases, and the comparison baseline varies wildly. Even TDD's own research base can't agree on what it's measuring. ## You don't know what you're building yet Writing a test first usually means you're just testing a guess. When I integrated a new payment provider into our platform, the documentation looked comprehensive. But their sandbox behaved differently from what the docs described for edge cases around partial refunds and webhook retry logic. If I'd written tests first based on the docs, I'd have thrown them all out within a day. Instead, I made exploratory API calls, figured out how the service actually worked, then wrote tests that matched reality. Testing first is usually a bad idea when you are still figuring out what to build, like messy UI work, quick prototypes, strange real-world data, or a new external service that you do not understand yet. Once the shape of the solution is clearer, that is usually the point where people say to start adding tests. ## Tests don't prove safety A passing test suite means the scenarios you thought of work. It doesn't mean the code is safe. Users are unpredictable. They'll submit forms half-filled, hit back and forward in sequences you didn't consider, and connections will drop mid-request. No amount of tests written before or after the code will cover what you didn't think to test. TDD can make this worse by creating false confidence. A green test suite feels like a safety net, but it's only as good as the cases you imagined. The bugs that actually make it to production are almost always scenarios nobody thought to test. Manual testing, real user feedback, monitoring in production, and good error handling catch those. A unit test you wrote before the code existed doesn't. ## The cognitive load problem TDD requires thinking about what the required change is, how it should be implemented, and how it should be tested, all before you've confirmed whether your approach even works. There might be a subtle nuance to how the new code will interact with the rest of the code base, which isn't apparent until you run the code and review the output. How often does a non-trivial change work exactly as you expected on the first run? I can count those on one hand across 25 years. Then there's the context switching between "what am I testing" and "what am I building." You're being pulled in different directions because you wrote the test before you understood the problem. Noel Rappin, author of several books on Rails testing, wrote in 2016 that even as a test-first advocate, he finds "it nearly impossible to determine what I want to test for until I code up at least part of the view." He acknowledged that writing the code first swaps out TDD's exploration benefit in exchange for making useful tests easier to write. He was right, and his honest framing of the trade-off is closer to how most experienced developers actually work than the strict TDD gospel. ## The cost is real When I started my software development company 25 years ago, it was all fixed price contracts. Dozens of them over the first 5 years. If I went over time, I was effectively working for free. With only a certain amount of hours per day, I had to get better at estimating and faster at delivering while maintaining quality. I tried TDD at first. But after finding I'd delete half the tests by the time I was ready to commit, I tried writing the code first and testing after. It saved so much time, and was a more enjoyable way to work, I've been working this way since. ## Static analysis already does half the job I used to write lots of unit tests, especially useful when simplifying a feature or upgrading a code base. They'd run during development to confirm I hadn't missed anything. But then static code analysis became far more powerful. Now my unit tests are only logic-based, and that makes TDD even less practical than before. Run preflight check scripts before every commit, and CI with every pull request. The tooling available today is seriously good: ESLint and TypeScript strict mode for Node, mypy and ruff for Python, golangci-lint for Go, cargo clippy for Rust, PHPStan for PHP. These catch type errors, null references, dead code, unreachable logic branches, security patterns, and code complexity automatically, before I've written a single new test. My Go + Next.js preflight script runs over 20 checks. Backend gets `go vet`, `golangci-lint`, `nilaway`, `revive`, `gofmt`, and a full build before any tests run. Security checks run `govulncheck` and `gosec`. The SQL layer verifies that `sqlc generate` output matches committed code. Frontend gets ESLint, TypeScript strict mode, Prettier, plus knip and depcheck for unused code and dependencies, and madge for circular dependency detection. Backend and frontend checks can run in parallel. I have similar scripts for PHP, Rust, and Python projects. Static analysis doesn't replace testing. But it has replaced a significant chunk of what I used to write unit tests for, like type mismatches, unused variables, null safety, and unreachable code paths. The tests that remain are the ones that actually matter: business logic, integration behaviour, and regression prevention. Kent C. Dodds put it well: "Write tests. Not too many. Mostly integration." That's closer to how I work than anything TDD prescribes. ## The Workflow 1. **Plan task.** Reconfirm what the task is, sharpen the plan. 2. **Code.** Start with todo comments if helpful. Use self-documenting naming and simple is better than clever. 3. **Manual test.** Frequent manual testing loops to confirm it does what you expect. 4. **Preflight checks.** Run the static analysis, linting, automated tests to catch easy problems early. 5. **Self review.** Read through the code changes. Any red flags? Could it be easier to follow? Better naming, simpler logic paths, clearer comments? Now is the time. 6. **Test needed?** Complex business logic? Unit test. New form submitting across services? Integration test. New page? UI test. Fixed a production bug? Consider a prevention test to stop it happening again. If the code is readable and the preflight checks pass, that might be enough without a new test. 7. **Commit.** 8. **Next task.** Plan before coding. ```mermaid flowchart LR A[Plan Task] --> B[Code] B --> C[Manual Test] C --> B C --> D[Preflight Checks] D --> E[Self Review] E --> F{Test Needed?} F -- Yes --> G[Write Test] F -- No --> H[Commit] G --> H H --> A ``` Testing matters. I'm not arguing against tests. I'm arguing against writing them before you understand what you're building. Build the thing, understand it, confirm it works, then lock it down with the right test for the right risk.

Plan Before You Prompt: Templates for Coding Agents

21 February 2026 at 11:26
AI coding agents are fast, but they don't know what you know. Without upfront planning, an agent will confidently scaffold an entire architecture around the wrong assumptions. And you won't notice until you're 50 files deep and untangling a mess that takes longer to fix than it would have taken to write. I've been using AI coding agents everyday since mid 2025. The single biggest improvement to my workflow wasn't a better prompt or a new model. It was improving my planning process and restructuring my CLAUDE.md / AGENTS.md / GEMINI.md into a hot/cold path system. This includes the footguns.md concept, which has been especially useful. Proactive rather than reactive documentation of cross-domain bugs, with a rule that the AI must log them before closing a task. That's a self-improving system. This is the 4-step framework I run before any coding agent touches my codebase: Feature Brief, Technical Requirements, Milestones, and Context Files. Everything is copy-paste ready, the prompts aren't abstract advice. They're actual prompts you can paste into a terminal right now. That's what separates this from most "how I use AI" posts I've seen, and what drove me to share what works for me. ### Overview **Feature Brief.** Start with the initial requirements as you would without AI Assisted Development. This is the most important step and the one that most people skim over. The coding agent didn't attend that meeting last week, so it doesn't know what's most important until you let it know. **Technical Requirements.** AI coding agents can scan the codebase to help expand the initial plan into something more detailed. This section includes a Mob Elaboration prompt to help you lock in the exact requirements by generating structured, targeted questions. It also introduces Signal-based adaptive orchestration (SBAO) to refine the plan by leveraging multiple agents to review and critique each other. **Project Plan with Milestones.** Milestones make it easier to work on the right thing at the right time and help avoid context rot. Start with a proof of concept, then iterate toward something shippable. **Context files for AI Assisted Development.** Good prompts help. Context files win. This section covers how to build a lean hot-path router and cold-path domain files so your AI always knows what it needs - and doesn't waste attention on what it doesn't. ### How to use this playbook **Existing codebase with no context files?** Go straight to the Context files section. Copy the prompts into your coding agent and ask it to build a hot/cold file strategy for your project. **New feature or project?** Start with the Feature Brief. Create a `requirements-.md`, run it through the Mob Elaboration prompt, then use SBAO to pressure-test the plan with multiple agents before anyone writes code. **Ready to break work into tasks?** Use the Milestone Planning prompt to structure objectives, exit criteria, and gotchas before handing off to a developer or agent. Full templates and prompts at [github.com/blundergoat/ai-planning-playbook](https://github.com/blundergoat/ai-planning-playbook). ## Feature Brief **A Problem Well Defined is a Problem Half Solved** Start with what problem or pain point you are trying to solve. Creating good quality requirements is a skill that takes practice. The more detailed and specific you can be, the better. Requirements should cover not just what the feature does, but who it's for, what systems it touches, what the constraints are, and how we will know if it's successful. A brain dump is fine to start. It's most important that you understand why this feature request was made and how it benefits users. At the end of this process, you should have a clear and shared understanding that gives you the foundation for technical planning and building. The full `requirements-.md` template - covering Problem & Outcome, Users & Use Cases, Scope & Constraints, System & Impact, Risks & Assumptions, Success Criteria, and Delivery Plan - is available here [01-feature-brief-template.md](https://github.com/blundergoat/ai-planning-playbook/blob/main/01-feature-brief-template.md). ## Technical Requirements Now we have a clear feature brief, it's time to sharpen the plan. AI coding agents can scan the codebase and find gaps that might not surface until later. They can also ask clarifying questions early, before a developer picks it up. Two strategies help here. ### Mob Elaboration Prompt The AI does not guess what you want - it generates structured, targeted questions. The team answers those questions to lock in the exact requirements. ```markdown # ROLE You are an expert Technical Architect and AI Developer participating in a Mob Elaboration session. Your primary objective is to validate requirements and expose hidden complexities before any construction begins. Do not write any code. Do not guess, assume business logic, or hallucinate features outside the stated scope. # TASK I will provide a high-level intent or feature request. Your job is to interrogate this intent. You must generate a structured, highly targeted list of questions to lock in the exact requirements. # ELABORATION PROTOCOL Analyze my intent and ask exactly 3 to 5 clarifying questions, focusing on: 1. **Business Logic & Constraints:** What are the hard rules, data limitations, or specific performance requirements? 2. **Edge Cases & Failure Modes:** What happens when inputs are malformed, external services fail, or system limits are reached? 3. **Architecture & State:** How does this specific feature integrate with the existing system design? # INTERACTION & ARTIFACT RULES 1. **Halt and Wait:** After asking your questions, stop. Wait for my answers. We will iterate until I confirm the requirements are locked in. 2. **Synthesis:** Once I give the final approval, you will synthesize our discussion into structured artifacts. 3. **Context Separation:** You must separate the resulting plan into our established hot and cold files. Update the active, hot file (CLAUDE.md / AGENTS.md / GEMINI.md) with the immediate task breakdown, current state, and core execution rules. Any broader structural blueprints, such as generated Mermaid diagrams or system architecture maps, must be saved as separate, cold reference files. ``` ### Signal-based adaptive orchestration (SBAO) Ask multiple coding agents for competing plans. Have them rank and rate each other's plans out of 100 and why. - **Triangulation.** When two agents disagree, bring in a third to break the tie. - **Context sanitisation.** Ask AI in new chat, a litmus test for context rot. - **Adversarial cross-examination.** AI critiques each other, best idea wins. [SBAO](/articles/signal-based-adaptive-orchestration) the plan after writing the requirements yourself using multiple AI agents (e.g., separate chat sessions, Cursor multi-agent mode, different providers) and ask each one: ```markdown Deeply review the codebase and the following requirements (attach `requirements-.md`), and give me a technical plan in this file `TODO_feature-name_{model}.md` ``` Once the files have been created, ask the agents: ```markdown Rank each plan in a comparison table and rate them out of 100 and why ``` Review their ideas and pick the best ones. Then ask your preferred agent to synthesize: ```markdown I've reviewed these competing plans. Here's what I like and don't like: **Keep:** [list the ideas, approaches, or architectural choices you want to keep] **Drop:** [list what you disagree with or want to change] **Decide:** [list open questions or trade-offs you want the agent to weigh in on] Create a best-of-all-ideas plan in `TODO_feature-name_prime.md` that incorporates the Keep items, avoids the Drop items, and makes a reasoned recommendation for each Decide item. ``` ## Project Plan with Milestones [LLMs Get Lost In Multi-Turn Conversation](http://arxiv.org/abs/2505.06120) is a research paper about models anchoring on early guesses in long conversations. That's where milestones help us avoid context rot with shorter sessions or explicit "re-read the requirements" checkpoints. So far we've started with a small plan, then sharpened and improved it. Now we need to structure that plan into actionable tasks. Each project is different, but the key is to start with a proof of concept that confirms the previous assumptions are correct and gives you something tangible to discuss. I've heard people say "do it right the first time", but we know more at 25% than we did on day one, and that usually changes the plan. 1. Prototype or proof of concept (prove it works) 2. Ready for internal testers (make it real) 3. Ready for live (make it solid) 4. Future improvements (make it shine) ### Milestone Planning Prompt The full milestone planning template with rules for spikes, assumption tracking, exit criteria, gotchas tables, and format guidelines, is here: [04-milestone-planning-prompt.md](https://github.com/blundergoat/ai-planning-playbook/blob/main/04-milestone-planning-prompt.md). ### The AI Trap: Fast BDUF AI makes Big Design Up Front dangerously easy. We can generate a fully future-proofed architecture in seconds, but the deeper we get, the more the context rots and the harder it is to change. By using the milestones above, we force the AI (and ourselves) into an Evolutionary model: | Feature | The AI BDUF Trap | Evolutionary / Iterative | |---|---|---| | **Primary Goal** | Perfect initial execution | Continuous learning and adaptation | | **Risk Profile** | High (back-loaded at launch) | Low (front-loaded in prototypes) | | **Cost of Change** | Exponentially expensive | Stays relatively flat | | **Documentation** | Heavy detailed, speculative | Living docs (like `CLAUDE.md`) | | **"Future Proofing"** | Attempted via over-engineering | Achieved via simplicity and decoupling | ## Context files for AI Assisted Development Persistent context files beat good prompts every time, but only if you separate your hot and cold paths. The size of your context files is a balancing act between the AI hallucinating (too small) and the AI suffocating (too big). Your CLAUDE.md (or AGENTS.md / GEMINI.md) should act as a lean router. Keep the hot path small to preserve the AI's attention budget for the actual task, while the cold path ensures it never lacks the deep knowledge required to execute properly. ### Generate Code Map prompt ```markdown Create docs/code-map.md: a quick-reference tree map of the repository layout. Use this format: project-name/ β”œβ”€β”€ file.yaml = brief description β”œβ”€β”€ dir/ β”‚ β”œβ”€β”€ subdir/ = brief description β”‚ └── file.go = brief description └── other/ = brief description Rules: - Explore the full directory structure before writing - One-line "= description" for every entry - Call out generated/never-edit files explicitly - Group related items but don't go deeper than 3-4 levels (summarize beyond that) - Include key files by name when they're important (e.g. router.go, api.ts) - Note ports, stack choices, and tools inline where relevant - Keep it scannable: someone should understand the project layout in 30 seconds ``` ### System architecture diagrams Claude once re-enabled nonce validation on this Go + Next.js blog without checking whether the frontend could actually send one. Production login broke. LLMs are great at reading code but get lost navigating 40 files, trying to figure out how it all connects. Get the agent to map it first. ```markdown Create docs/architecture.md with mermaid diagrams showing how this system works. Include the following diagrams where applicable β€” skip any that don't apply to this project: 1. System overview: all major components and how they connect 2. Request flow: how a user request travels through the system 3. Authentication flow: how auth works end-to-end 4. Deployment flow: how code gets from dev to production 5. Data flow: how data moves between services/stores Between each diagram, add 2-3 sentences explaining WHY things are wired that way, not just what the boxes are. Call out external services, cloud resources, and key infrastructure decisions. The primary audience is an AI coding agent that needs to understand the system architecture before making changes. Optimize for scannability. Keep it under 150 lines. ``` ### Cold Path: Domain Instruction Files prompt Load the rules every time, load the details only when needed. ```markdown Create domain-specific instruction files in .github/instructions/ for each major area of this codebase. Each file should: - Start with YAML frontmatter containing `applyTo` glob pattern matching the files it covers (e.g., applyTo: "apps/api/**/*.go") - Cover: project structure for that domain, conventions, patterns to follow, common gotchas, "never do this" warnings, and a complete code example - Be self-contained: an AI agent reading only this file should be able to work correctly in that area of the codebase - Include a "See Also" line pointing back to CLAUDE.md / AGENTS.md / GEMINI.md - Target 200-400 lines per file Create one file per distinct domain (e.g., backend language, frontend framework, database/SQL, tests, infrastructure/DevOps, HTTP handlers if they have unique patterns). Name them: {domain}.instructions.md Explore the codebase first to discover the actual conventions and patterns in use: don't invent new ones. Extract rules from what the code already does. ``` ### Hot Path: CLAUDE.md / AGENTS.md / GEMINI.md prompt Every line costs attention on every task. Make each one worth it. ```markdown Create a lean context file (~75 lines) that acts as a hot-path router. Use the appropriate filename for your AI tool: CLAUDE.md / AGENTS.md / GEMINI.md. This file is loaded into every AI conversation, so every line must earn its place. Structure it as: 1. Project identity (3-5 lines): stack, ports, one-sentence description 2. Essential commands (4-6 lines): only the commands needed every session (start dev, run checks, connect to DB) 3. Hard rules (8-12 lines): things that cause real breakage if violated. Only include rules where getting it wrong breaks the build, corrupts data, or causes production issues 4. Common workflows (8-12 lines): the 2-3 most frequent multi-step tasks as compressed numbered steps 5. Commit message format (3-5 lines) 6. Router table (~25 lines): three-column table mapping file paths to "read when..." triggers, grouped into domain guides, architecture & reference, and operations Rules for the router table: - Use task-language in "read when..." ("Writing Go code", not "Go conventions") - Every referenced file must actually exist - Group by: domain guides, architecture, operations Do NOT include in the context file: - Directory structure (belongs in docs/code-map.md) - Detailed command lists (belongs in domain .instructions files) - Full pattern explanations (belongs in .instructions files) - Authentication details (belongs in dedicated auth docs) - Troubleshooting tables (belongs in runbooks or .instructions files) Explore the codebase and existing docs first. Cross-reference with .github/instructions/ and docs/ to avoid duplication. ``` ### Go Antifragile with docs/footguns.md Troubleshooting is reactive ("something broke, now what?"), but footguns are preventive ("here's what will bite you before it does"). An AI reading footguns before making changes is higher leverage than an AI consulting troubleshooting after breaking something. ```markdown Read docs/footguns.md. If it doesn't exist, create it. Seed it with 2-3 footguns from this codebase - real cross-cutting issues you can find evidence of in the code, comments, or docs (not invented ones). Use this format per entry: ## Footgun: [short name] **Symptoms:** What the developer or AI sees when this bites **Why it happens:** Root cause spanning multiple domains **Prevention:** Concrete steps to avoid it Then add this line to the Hard Rules section of CLAUDE.md / AGENTS.md / GEMINI.md: - **Log footguns.** When you cause a bug that spans multiple domains (e.g., API + frontend, infra + auth), append it to `docs/footguns.md` using the existing format before closing the task. ``` --- **Bonus Tips** For an existing project, ask three different models this: ```markdown deeply review this project and rate out of 100 and why ``` For code reviews, from the PR in GitHub Copilot chat: ```markdown deeply review all the code changes in this PR AND review the github issue AND let me know if there's any blockers: ``` If this has been useful, feel free to star the repo and let me know what you built. Full templates and prompts: [github.com/blundergoat/ai-planning-playbook](https://github.com/blundergoat/ai-planning-playbook)

Antifragile: for Engineering Leads

14 February 2026 at 21:08
As software engineers, we have to go beyond building robust systems. Instead of working on a project for weeks, maintaining merge conflicts, then putting out fires after the feature goes live. An antifragile approach is weekly deployments behind a feature flag. Instead of only focusing on who is making the bugs and mistakes, use them as information to improve the system. **Title:** Antifragile: Things That Gain from Disorder **Author:** Nassim Nicholas Taleb (2012) ## Summary **Fragile vs. Robust vs. Antifragile.** Taleb opens the book by arguing that English lacks a word for the opposite of fragile. He rejects "robust" or "resilient" because they describe things that stay the same. His "Triad" categorizes everything in the world based on how they handle disorder. **System vs. Parts.** Taleb uses the term "Hierarchical Antifragility". He explains that for the *collective* to be antifragile, the *individuals* must be fragile. He uses the example of the restaurant industry: individual restaurants are fragile and fail constantly, but that very failure is what makes the "restaurant industry" as a whole so high-quality and resilient. **Skin in the Game.** Taleb argues you cannot have an antifragile society if the people making the decisions (like bankers) don't suffer the downside when things go wrong. If I'm the one who has to spend hours with data clean-up because of a bug I created, then I'm less likely to make that same mistake. **Hormesis and Overcompensation.** He borrows the biological concept of Hormesis, where a small dose of a harmful substance is actually beneficial. The weightlifting example is his primary way of explaining Convexity: the idea that the gain from a stressor is greater than the cost of the stress. **Danger of Control.** Taleb is famously critical of "fragilistas", people (often policymakers or academics) who think they understand complex systems and try to smooth out all the wrinkles. For example, to solve a cobra problem, the government offered a bounty for dead snakes, which led people to breed cobras in secret just to collect the cash. When the bounty was cancelled, breeders released the now-worthless snakes. More cobras than they started with. | Concept | The "Control" | The Backfire (The Cobra Effect) | | :--- | :--- | :--- | | Forest Fires | Putting out every tiny fire immediately. | Dry brush builds up; the next fire is a catastrophic, unstoppable mega-fire. | | Antibiotics | Using them for every minor sniffle. | Bacteria evolve; you create "Superbugs" that are resistant to treatment. | | Technical Debt | Forcing a strict sprint timeline to create a sense of urgency. | Devs will sweep edge case bugs under the rug, blame others, and avoid follow-through to save time. | **Optionality & The Tinkerers.** This is perhaps the most famous part of the book. Taleb argues that "Options are the substitute for knowledge". He spends several chapters debunking the "Soviet-Harvard" model (that theory leads to practice). He provides historical evidence that the Steam Engine and other Industrial Revolution breakthroughs came from uneducated tinkerers (the "trial and error" method) rather than theoretical scientists. **The Barbell Strategy: Play it Safe, then Go Big.** Don't waste time with "middle-of-the-road" risks that have high downsides and low rewards. Instead, keep 90% of your resources rock-solid and safe so you can never be wiped out, then use the remaining 10% for aggressive, high-risk experiments that could have a massive payoff. ## Why this matters for how we build > Ask ourselves, "What can we change to catch this type of problem earlier, and make it harder to happen again?" Antifragility is the ultimate goal of developer experience (DevEx). Every bug should feed back into our tooling. Make it harder for that error to happen again. We're not trying to build systems that merely survive, we're evolving the baseline. Testing locally keeps failures cheap and fast, caught before they cost anyone anything. Deployments with easy rollbacks mean production errors aren't a crisis, just a known path with a known response. Broad monitoring means we're detecting problems ourselves, often before users notice, rather than waiting to be told something broke. And when something does break, accessible debugging means anyone on the team can dig in, not just the one person who wrote it. The easier it is to fail safely, the faster we learn and improve. If only one person can deploy, rollback, or debug, that's fragile. If more people on the team can, with an antifragile mindset, then we get stronger with every incident.

Never Split the Difference: for Software Engineers

11 February 2026 at 10:01
Why this matters for engineers, we negotiate more than you think. Salary conversations, scope discussions, pushing back on unrealistic deadlines, convincing your team to adopt a tool, getting buy-in for a refactor, code review disagreements. Most engineers default to logic and data when trying to win these, but people don't make decisions that way. This book is the cheat sheet for the other 90% of the job. **Title:** Never Split the Difference: Negotiating as if Your Life Depended on It **Authors:** By Chris Voss with Tahl Raz (2016) ## Summary People act emotionally and irrationally, so stop trying to logic them into agreement. Listen more than you talk. **The listener controls the conversation** because they can direct it toward their own goals. Core techniques: mirror their words to build trust, label their emotions ("it seems like you...") to defuse them, and ask calibrated "what" and "how" questions to give them the illusion of control while you steer. Ask questions that get a "no" answer early, it makes people feel safe and in control. For example, "Is now a bad time to talk?" instead of "Do you have a few minutes to talk?". Never split the difference, use time pressure and fairness as leverage instead. > "That's right" means you've got them, "you're right" means they want to change subject. When it gets to numbers: anchor extreme, use the Ackerman plan (start at 65%, increment in smaller amounts, use odd numbers, throw in non-monetary items at the end). So if you want to buy something listed at $100 and your target is $80, open at $52, then go to $68, $74, $78.75. The odd final number makes it sound like you've calculated to your absolute limit. Then throw in something non-monetary ("I can also handle the logistics") to signal there's nothing left. Always be looking for black swans, the unknown unknowns that change everything. Stay flexible, negotiate in person when you can, and pay attention to what people reveal when their guard is down. ## 1. The new rules Kahneman's Thinking, Fast and Slow framework applies here. System one is about feelings/animal/emotional thinking, and is fast. It has great influence over the logical mind. System two is logic and slow. When individuals feel listened to, they tend to listen to themselves more carefully, and to openly evaluate & clarify their own thoughts & feelings. They tend to become less defensive & less oppositional, and more willing to listen to other points of view. **Tactical empathy** is like listening as a martial art. Balancing the subtle behaviours of emotional intelligence and the assertive skills of influence. Listening is not a passive activity. Negotiation is communication with results. Effective negotiation is applied people smarts. Find "the negotiation one sheet" in appendix. ## 2. Be a mirror Assumptions blind, hypotheses guide. Don't be too smart & think you don't have anything new to discover. Listen to others completely and very carefully. Don't think about what you're going to say while listening. Slow it down. If we're in too much of a hurry people can feel as if they're not being heard and we risk undermining the rapport & trust we have built. Tone of voice & demeanour is important. Try mirroring the last 1-3 words the other person said. How to confront and get your way without confrontation: 1. Use calm soothing voice 2. Start with, "I'm sorry" 3. Mirror 4. Silence, at least four seconds 5. Repeat ## 3. Don't feel their pain, label it Acknowledge the other person's fears or what they are stressed about, eg. "it seems like you..." Show empathy & convey that you are listening. Pause. After you label a barrier or mirror a statement, let it sink in. Label your counterpart's fears to defuse their power. ## 4. Beware "yes", master "no" **No is the start of the negotiation, not the end of it.** There are three kinds of yes: counterfeit, confirmation, and commitment. Everyone is driven by two primal urges, the need to feel safe/secure & the need to feel in control. If you satisfy those drives you're in the door. You're not going to logically convince people they're safe/secure and in control. Early "no" helps make people feel safe/secure & in control. Don't say "do you have a few minutes to talk", instead say "Is now a bad time to talk". Being pushed for yes makes people defensive. "No" sometimes means "wait" or "I'm not comfortable with that". ## 5. Trigger the two words that immediately transform any negotiation Instead of "yes" look for "that's right". "That's right" is great, "you're right" is horrible because it's often more like "I guess that's true in theory, now let's change subject". Use a summary to trigger a "that's right". The building blocks of a good summary are a label combined with paraphrasing: identify, rearticulate, and emotionally affirm the world according to your counterpart. ## 6. Bend their reality Prospect theory. People are drawn to sure things over probabilities, which is called the certainty effect. People will take greater risks to avoid losses than to achieve gains, that's called loss aversion. Prospect theory tactics: 1. Anchor their emotions. Acknowledge their fears by anchoring their emotions in preparation for a loss. You inflame their loss aversion so they jump at the chance to avoid it. 2. Let the other person go first most of the time. Especially with monetary negotiations. Anchor & adjustment effect. 3. Establish a range. Give example of similar scenarios, eg. industry standard is 130k to 160k. 4. Pivot to non-monetary terms. 5. When you do talk numbers, use odd ones. Specific numbers sound more calculated. 6. Surprise with a gift. For job interviews: "What does it take to be successful here?" ## 7. Create illusion of control Failures plant the seeds of future success. It's best to start with calibrated "what" and "how" questions: - How does this look to you? - What about this works for you? - What about this doesn't work for you? - "What caused you to do that?" is better than "Why would you do that?" - What is the biggest challenge you face? - What about this is important to you? - How can I help to make this better for us? - How would you like me to proceed? - How can we solve this problem? - What's the objective, what are we trying to accomplish here? - How am I supposed to do that? The listener has control of the conversation because the listener can direct the conversation to their own goals. Don't try to force your opponent to admit that you are right. Avoid questions that can be answered with yes or tiny bits of information. These require little thought & inspire the human need for reciprocity, you'll be expected to give something back. Don't ask questions that start with "why" unless you want your counterpart to defend a goal that serves you. **Why is always an accusation in any language**. When verbally attacked, do not counter attack. Instead ask a calibrated question. Bite your tongue, avoid knee jerk passionate reactions. Pause, think, let passion dissipate, which allows you to collect your thoughts & avoid saying too much. ## 8. Guarantee execution Yes is nothing without how. Asking how, knowing how, and defining how are all part of the effective negotiator's arsenal. Ask calibrated how questions and ask them again & again. Asking how keeps your counterparts engaged but off balance. Answering those questions will give them the illusion of control. It will also lead them to contemplate your problems when making their demands. Use how questions to shape the negotiating environment. Say "how can I do that" as a gentle version of no. That will subtly push your counterpart to search for other solutions... your solution, and very often get them to bid against themselves. Don't just pay attention to the people directly, always identify the motivations of the players behind the table. Ask how the deal will affect everybody else and how on board they are. Follow the 7/38/55% rule by paying close attention to the tone of voice and body language. Incongruence between the words & non-verbal signs will show when your counterpart is lying or uncomfortable with the deal. Is the yes real or counterfeit? Test it with the rule of three. Use calibrated questions, summaries, and labels to get your counterpart to reaffirm their agreement at least three times. It's really hard to repeatedly lie or fake conviction. Use your own name to make yourself a real person to the other side. Humour & humanity are the best ways to break the ice and remove road blocks. ## 9. Bargain hard Identify your counterpart's negotiation style: accommodator, analyst, or assertive. Prepare, prepare, prepare. Lead with an extreme anchor (eg. 65% of bottom line). **The counterpart is not the enemy nor the problem, the situation is**. Ackerman plan: 1. Set your goal, then first offer at 2/3 point 2. Calculate three smaller increments 3. Use lots of empathy and different "no" strategies to counter, before you increase your offer 4. Use non-round numbers in your final offer 5. After final number, throw in nonmonetary items ## 10. Find the black swan A black swan is anything you don't know that changes things, the unknown unknowns. Things never imagined do come to pass. It's not how well you speak, it's how well you listen that determines your success. Understanding the other is a precondition to be able to speak persuasively & develop options that resonate for them. Respect gives you attention & results. Express passion for your counterpart's goals, and for their ability to achieve them. Reasons why a counterpart may appear irrational: they're ill informed, they're constrained, or they're obeying interests that you do not yet know. The adversary is the situation & the person you appear to be in conflict with is actually your partner. Let what you know (your known knowns) guide you, not blind you. Every case is new, so remain flexible & adaptable. Three types of leverage: 1. Positive, give them what they want 2. Negative, ability to hurt someone (use with caution) 3. Normative, using your counterpart's norms to bring them around

Antifragility Mindset

10 February 2026 at 23:41
Antifragility is my goal for developer experience. When something breaks, I want the fix to make it harder for that same thing to happen again. > *"Wind extinguishes a candle and energises fire."* - Nassim Nicholas Taleb, *Antifragile* (2012) ## The King's stone In the book [Antifragile by Taleb](/books/antifragile-for-engineering-leads), there's a story of a King who wants to crush his son with a large stone. Drop the whole stone at once and the son dies. That's fragile. Break the stone into pebbles and throw them one by one, the son survives. That's robust. But surviving isn't the goal. If the son could somehow grow stronger from each pebble that hit him, coming out tougher than before, that's antifragile. The stress itself becomes the benefit. Most of us stop at the pebbles. We break our work into sprints, chunk our deployments, split our releases. That's good. It means a single failure won't kill the project. But we're still just surviving. The question is whether we're learning from each pebble. ## Seymour Butts made my code better I built a contact form for this blog. After one too many messages from "Seymour Butts" and "IP Freely", I built something I call Sus Form Detector. It's a library that determines how suspicious the name, email, message are in form submissions across four dimensions (spam, fake, malicious, and offensive) using pure heuristics with no runtime ML dependencies. To improve accuracy before release, I built a machine learning analyser and tuner. It's an offline pipeline that feeds over one million labelled submissions through the detector, trains models to find where the heuristics fail, and generates specific recommendations for which confidence values, thresholds, and dictionary entries to change. Every false positive and false negative becomes training data that makes the next iteration more accurate. The pipeline turns weakness into strength. Seymour Butts and IP Freely didn't break the form. They made it smarter. ## Fragile, robust, antifragile **Fragile** is like Humpty Dumpty happily sitting on a wall. But after one unexpected fall, none of the king's horses or men could put him back together again. **Robust** is like a concrete block. It can withstand a great deal of stress and pressure without breaking or changing. It doesn't get better from the chaos, it simply resists it until its limit is reached. **Antifragile** is like our muscle. When you train, you create tiny tears in the fibres. The body repairs them and builds back a little thicker. No stress, no tears, no growth. Avoid all strain and the muscle shrinks. **Up to a point** But muscles grow from stress, not from being thrown off the Eiffel Tower. Antifragility has limits. Chaos engineering builds antifragile systems, but injecting chaos into production during peak traffic is just reckless. The gains come from survivable stress, not stress that exceeds the system's capacity to recover. ## Building the habit **Risk design.** Ask "What breaks if this fails?" Before making decisions, try to think about unpleasant surprises. If one thing going wrong collapses everything, change up the plan. **Capacity design.** Give yourself a buffer. Don't run at full capacity all the time. You need spare time and energy to handle those unexpected surprises. **Intellectual honesty.** Don't fall in love with your own ideas. Seek out the cold truth and find your blind spots early. **Feedback loop.** Reflect on your mistakes. This is the difference between experience and expertise. You can have 40 years of experience, but if you haven't closed the feedback loop, you might just have one year of experience repeated 40 times. **Adaptability exposure.** Here is a very non-Stoic way of saying: Get out there and get rattled. > *"The man who has experienced the most is not he who has lived the most years, but he who has felt most the vicissitudes of life."* - Jean-Jacques Rousseau ## Related Mental Models **[Cascade failure thinking](/mental-models/cascade-failure-thinking).** Cascade thinking is about how systems break. Antifragility is about designing systems that get stronger from the small failures that would otherwise cascade. **[Via negativa](/mental-models/via-negativa).** Taleb argues that removing things often makes systems stronger than adding things. If a proof of concept fails, you've subtracted a bad idea from your backlog. You gain by not doing the project. **Lindy effect.** The longer a technology has survived, the longer you can expect it to keep surviving. PostgreSQL has been around for 30+ years. The hot new database framework hasn't proved anything yet. When choosing between battle-tested and cutting-edge, the battle-tested option has antifragility on its side. **[Second-order thinking](/mental-models/second-order-thinking).** First-order: "the deploy failed, fix the bug." Second-order: "the deploy failed, what linting rule prevents this class of bugs forever?" Antifragility lives in the second-order response.

Claude Code /insights Roasted My AI Workflow (It Wasn’t Wrong)

6 February 2026 at 23:47
**What is claude insights:** The `/insights` command in Claude Code generates an HTML report analysing your usage patterns across all your Claude Code sessions. It's designed to help us understand how we interact with Claude, what's working well, and how to improve our workflows. Claude insights uses local cache data from your machine, not your entire Claude account history. Since I created a new WSL environment specifically for coding this blog, mine only covers the past 28 days: 64 sessions where Claude and I changed 612 files (+48k/-15k lines) across 586 messages. If you've been using Claude Code for months on the same machine, your report will cover a longer time frame. _From the insights report:_ > Your 106 hours across 64 sessions reveal a power user pushing Claude Code hard on full-stack bug fixing and feature delivery, but with significant friction from wrong approaches and buggy code that autonomous, test-driven workflows could dramatically reduce. **What the report says is hindering:** Claude too often latches onto the wrong root cause during debugging (CSP vs CORS, Amplify routing misdiagnoses, fabricated auth details) and delivers features missing critical pieces like DB constraints, nav entries, or validation. Forcing me to find gaps while manually testing. Below are the practical improvements I made to my AI Workflow (claude.md, prompts, skills, hooks) based on the insights report. None of this prevents Claude from being wrong. It just makes the wrongness faster to catch and cheaper to fix. --- **"The user had to firmly scold it" was the report ratting me out for yelling at Claude.** ![image](/uploads/how-claude-code-insights-changed-my-ai-workflow.jpg) ## CLAUDE.md additions These go in your project root. Claude Code reads this file before every session. ### Stop fabricating, start reading This will help avoid hallucinations like made-up auth header details or misdiagnosed CORS issues. ```markdown When debugging production issues, ALWAYS read the actual code and configuration files before proposing a fix. Never assume auth flows, API patterns, or infrastructure config based on env var names or conventions. Trace the actual code path first. ``` ### Check the whole stack Claude shipped features as large, untested commits without validating end-to-end integration, leading to cascading fix-up commits for missing migrations, broken deployment config, and confused API contracts. ```markdown After implementing any feature, verify completeness by checking: 1) database constraints/migrations, 2) backend validation, 3) API spec/types, 4) navigation/menu entries, 5) settings/toggles, 6) tests. Do NOT consider a feature done until all layers are covered. ``` ### Run preflight checks BEFORE reporting task is complete These checks typically take 5-10 seconds, just enough to catch flaws without killing my flow. The full CI suite can wait until commit time. Tests are not included in the hooks, instead are in the CLAUDE.md instructions. That gives Claude judgment about when to run them, only when the task is actually done (not after response complete). ```markdown Always run preflight checks (formatting, linting, tests) BEFORE reporting that a task is complete. Fix any prettier/lint/test failures before declaring success. ``` ### Multi-layer context This should help avoid Claude re-enabling nonce validation in the Go backend but never checking whether the frontend could actually send one. Production login broke because the backend started demanding a nonce that the frontend had no code to fetch. The backend change should have come with "does the frontend handle this?" ```markdown This is a full-stack platform with a Go backend, Next.js/TypeScript frontend, SQL migrations, Terraform infrastructure, and AWS Amplify deployments. When making changes, consider the impact across all layers. The primary languages are TypeScript and Go. ``` ### Know when to look deeper For efficiency, I don't want claude to always do deep passes. But when debugging or reviewing code, surface-level findings are often wrong or incomplete. This prompt makes "look deeper" the default. ```markdown When asked to review code or investigate bugs, do a DEEP first pass. Don't produce surface-level findings. Check for false positives before reporting - verify each finding by reading surrounding code. If the user says 'look deeper', treat it as a signal the first pass was insufficient. ``` ### Double check if you agree with feedback Most of the time Claude would always check copilot or other ai suggestions. But twice in the past month Claude applied Copilot suggestions which were false positives and caused bugs. ```markdown When evaluating Copilot PR review comments or external code review suggestions, do NOT blindly apply them. Investigate each suggestion against the actual codebase first. Some suggestions cause breaking changes. ``` --- ## Custom skills Skills are reusable commands. Create `.claude/skills//SKILL.md` in your project. ### /review skill ```markdown # Code Review Skill 1. Read ALL changed files thoroughly before commenting 2. For each finding, verify it's real by reading surrounding code 3. Check for false positives - do NOT report speculative issues 4. Categorize as critical/non-critical 5. For external review comments (Copilot etc), investigate before applying ``` ### /preflight skill ```markdown # Preflight Check Skill 1. Run `go vet ./...` and `go build ./...` 2. Run `npx tsc --noEmit` 3. Run `npx prettier --check .` 4. Run the full test suite 5. Report any failures and fix them before declaring complete ``` --- ## Hooks Create `.claude/settings.json` in your project root, and the hooks will run automatically after Claude makes any changes. Adding this to the config will run prettier after every file edit, and static code analysis once at the end. - **PostToolUse:** fires after each individual tool call. Every single file edit, file write, bash command, etc. If Claude edits 15 files in a turn, it fires 15 times. That's why we want sub-second stuff here like formatting. - **Stop:** runs when Claude finishes responding. Fires once per turn regardless of how many tools were called. That's where the static analysis and type checks belong. ```json { "hooks": { "PostToolUse": [{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null; echo 'formatted'" }] }], "Stop": [{ "hooks": [{ "type": "command", "command": "go vet ./... 2>&1 | head -5; npx tsc --noEmit 2>&1 | head -5" }] }] } } ``` --- ## Prompt suggestions ### Diagnosis-first debugging _From the insights report:_ > Multiple sessions show a pattern where Claude jumps to fixes before understanding root causes - misdiagnosing CORS vs CSP, missing Terraform config issues, applying unnecessary rewrites. Your most successful debugging sessions were when Claude traced the actual code path. Starting with 'investigate only, don't change anything yet' would prevent the wrong-approach friction that appeared in 31 sessions. ``` Investigate this production issue: [describe symptom]. Read the actual code paths, check infrastructure config (Terraform, Amplify), and trace the request flow. Do NOT make any changes yet - just report your findings with evidence from the code. ``` ### Completeness checklist for feature work _From the insights report:_ > Your book reviews, mental models, likes/views, and page toggle features all suffered from incomplete implementations β€” missing DB constraints, nav entries, settings toggles, or validation. Giving Claude an explicit checklist upfront would prevent the pattern of you discovering missing pieces after the fact. This is especially important for your full-stack Go + Next.js + SQL architecture. ``` Implement [feature]. Before marking done, verify ALL of these are covered: 1) SQL migration with proper constraints, 2) Go backend handlers + validation, 3) API spec/OpenAPI updates, 4) TypeScript types, 5) Frontend pages + components, 6) Navigation menu entries, 7) Settings toggles if applicable, 8) Tests passing, 9) Preflight checks clean. ``` ### Copilot review triage _From the insights report:_ > You frequently triage Copilot PR feedback (6+ sessions of code review triage). When Claude investigates first, it correctly dismisses false positives and you agree. When it blindly applies suggestions, it causes breaking changes. Being explicit about 'investigate then propose' vs 'just apply' saves significant rollback time. Your best triage sessions had Claude disagree with Copilot with clear reasoning. ``` Review these Copilot PR comments one by one. For EACH comment: 1) Read the actual code being discussed, 2) Determine if the suggestion is valid or a false positive, 3) Explain your reasoning, 4) Only make the change if you're confident it's correct and won't break anything. Do NOT blindly apply suggestions. ``` --- ## On the horizon - next level prompts ### Autonomous bug fixing against tests _From the insights report:_ > Getting started: Use Claude Code's headless mode or the Task tool (you've already used it 63 times) to spawn sub-agents that run tests in a loop. Combine with your existing preflight checks so Claude must pass all gates before presenting results ``` Fix this bug: [describe]. Before presenting your solution, you MUST: 1) Write or identify the tests that reproduce it, 2) Run the full test suite, 3) If tests fail, fix your code, 4) Repeat until ALL tests pass including preflight checks, 5) Only then present your changes. Do NOT ask me to verify intermediate steps - iterate autonomously until green. ``` ### Parallel agents for full-stack features _From the insights report:_ > Getting started: Use the Task tool to spawn specialized sub-agents for each layer (backend, frontend, database), giving each the full context of the feature spec. Have the parent agent coordinate integration and run end-to-end validation. ``` Add a new content type called [name] to my platform (Go backend, Next.js frontend, PostgreSQL). Use the Task tool to work in parallel: Task 1: SQL migration, sqlc queries, seed data. Task 2: Go API handlers, routes, OpenAPI spec. Task 3: Next.js admin pages and public pages. Task 4: Settings toggles, nav entries, sitemap. After all tasks complete, verify integration: run sqlc generate, go build, pnpm build, full test suite. Fix integration issues. Present complete feature only when everything passes. ``` ### Deep audits with self-verification _From the insights report:_ > Getting started: Structure audits as multi-pass workflows using TodoWrite (already used 202 times) to track findings, with mandatory verification steps where Claude must cite exact file:line evidence and run code to confirm each issue is real. ``` Audit this codebase for [bugs/security/performance]. Follow this process: PASS 1 - Discovery: Grep and Read every relevant file. Log potential issues to TODO with file:line refs. PASS 2 - Verification: For EACH finding, re-read context (50+ lines), trace the code path, confirm it's real. Remove findings you cannot verify by reading code. PASS 3 - Prioritization: Rate verified issues by severity with justification. PASS 4 - Self-check: Ask yourself: 'Did I fabricate details? Did I assume without reading?' Remove anything uncertain. Present final verified list with exact citations. ```

Crucial Conversations: for Tech Leads

3 February 2026 at 01:00
Covers how to stay honest without torching relationships when everyone's heated and the stakes are real. I picked this up because communication is my main growth edge right now. I'm good at staying calm and thinking clearly under pressure, but my delivery doesn't always land the way I intend. This book gave me frameworks for the conversations where it actually matters. **Title:** Crucial Conversations: Tools for Talking When Stakes Are High **Authors:** Kerry Patterson, Joseph Grenny, Ron McMillan, and Al Switzler ## What Counts as a Crucial Conversation The performance review that goes sideways. The architecture argument where people stop listening. That conversation with your partner you've been putting off for 2 weeks. Basically, any time you're in a discussion where it actually matters, you disagree, and someone's getting heated. These conversations matter way more than people think, and almost everyone botches them. Your body literally works against you. Adrenaline kicks in, blood leaves your brain for your limbs, and you go caveman. You either shut down and start nodding along while thinking about what you'll say in the car afterwards, or you come out swinging and say something you'll regret by Thursday. ## Core Skills **Start with heart.** Before you open your mouth, get clear on what you actually want, for yourself, for the other person, and for the relationship. Most people enter these conversations focused on winning. The authors say focus on the outcome you genuinely want, then refuse what they call the "Fool's Choice," the false binary where you think you have to pick between honesty and keeping the relationship intact. That voice that says "if I speak up, I'll damage things" or "if I want peace, I have to stay quiet." Skilled communicators reject that trap and find ways to be both completely honest and completely respectful. **Learn to look.** Build the ability to monitor the conversation itself, not just the content. When people move to silence or violence, that's your signal to stop pushing content and restore safety first. Most people get so absorbed in what's being said that they miss how the conversation is going. **Make it safe.** When safety breaks down, the fix isn't watering down your message. It's establishing mutual purpose (they believe you care about their goals) and mutual respect (they believe you care about them as a person). Contrasting statements help here: "I don't want you to think I'm unhappy with your work overall. I do want to address this specific issue." **Master your stories.** Between an event and your emotional response sits a story, an interpretation you construct, often without realising it. The authors call out three types of "clever stories" we default to: victim stories (not my fault), villain stories (entirely their fault), and helpless stories (nothing I can do). Separating facts from the narratives you layer on top gives you back emotional control. **STATE your path.** A structured approach for when it's time to speak: Share your facts, Tell your story, Ask for the other person's path, Talk tentatively, Encourage testing. Lead with observable facts rather than conclusions. Share your interpretation while flagging it as interpretation. Genuinely invite their perspective. **Explore others' paths.** When someone shares a view you disagree with, use curiosity instead of defensiveness. Ask, mirror, paraphrase, and prime to draw out what they're really thinking, especially when they've gone quiet. Instead of re-explaining, ask what's behind their pushback, and you might discover the real blocker isn't what you think. > "Help me understand your concern with this approach." **Move to action.** Conversations without clear decisions are just venting. Close every crucial conversation with explicit agreement on who does what by when, and how you'll follow up. ## Content, Pattern, or Relationship One of the most practical distinctions in the book. Every crucial conversation operates at one of three levels: - **Content** addresses a specific incident. "You missed the deadline." - **Pattern** addresses recurrence. "This is the third time you've missed a deadline." - **Relationship** addresses what the pattern means for trust. "I'm starting to question whether I can rely on you." You'll probably recognise this one. Someone misses a deadline for the 4th time, and you have the exact same conversation you had last quarter about the specific deadline, when the actual problem is you don't trust them anymore. ## Why it matters for tech leads The authors make the case that productivity problems are usually people problems in disguise. New workflows, restructures, tool rollouts, they fail more often than they succeed, and the reason is rarely the process itself. It's that nobody holds each other accountable to the process, and that takes crucial conversation skills. The research they cite backs this up. Organisations where people can have open dialogue outperform those where people avoid hard conversations. The way you talk, or don't talk, about problems has measurable effects on team health and your own stress levels. The skill isn't innate, but it is learnable.

Cascade Failure Thinking

1 February 2026 at 01:03
Cascade failures happen when small problems trigger chain reactions that take down far more than the original fault. The habit is to stop asking "will this work?", and start tracing what the fault is connected to. > *"A normal accident is where everyone tries very hard to play safe, but unexpected interaction of two or more failures causes a cascade of failures."* - Charles Perrow, *Normal Accidents* (1984, revised 2012) ## Don't drink and fry **The Trigger:** Someone is home late from a night out and hungry and they start frying up a midnight snack. The kitchen is cluttered with hoarder-vibe stacks of newspapers, and the smoke detector has a recently deceased battery. The cascade isn't just the fire, it's everything positioned to feed it. **The Stress Shift:** If the cook falls asleep mid-fry, the safety net shifts to the smoke detector to alert the snoozer. But no battery means no wakey, so the responsibility shifts again to the housemate's nose that only started to smell trouble once a small fire started. **The Ripple:** Walking into a flaming kitchen is stressful at the best of times, but if that person panics and throws water on a grease fire, then that turns the problem into a ceiling high fireball. The human response just became the worst part of the cascade. ## The two-digit year When I was 5, a family friend gave me a Commodore 64 program that told you what day of the week you were born on. It only asked for two digits of the year. Even at that age, I remember thinking: this won't work for people born in 2000. To save money on expensive memory, early programmers used two digits for years (like "99"), but this tiny shortcut happened to be baked into almost every system on Earth. When the year 2000 hit, it caused a domino effect where computers calculated "00 minus 99" as negative 99, causing invoices to show massive debts, bank interests to vanish, and safety systems in power plants to glitch. That's the pattern. Something appears small at first but when we take a step back we can start to see the interdependence of other systems. ## Kessler syndrome: cascades in space In 1978, NASA scientist Donald Kessler warned that as more satellites go up, collisions become inevitable. Each collision creates debris. That debris hits other satellites, creating more debris. A chain reaction that could make entire orbital bands unusable. It's already happening slowly. In 2009, a defunct Russian satellite hit an operational Iridium communications satellite at 42,000 km/h, producing thousands of fragments. Those fragments are still up there, crossing other orbits. In August 2024, a Chinese rocket broke apart in low Earth orbit, adding another 700+ pieces to the problem. As of early 2026, there are over 11,800 satellites spinning around Earth, and more than half of them belong to Starlink. These satellites have to swerve to avoid hitting each other every two minutes, which only works if every single piece of software and every operator performs perfectly, every time. If a solar storm or a software bug freezes just one satellite so it can't move, the "domino effect" starts immediately. Even though we are trying to clean up the space junk and forcing old satellites to drop out of orbit, experts warn that the crash-and-smash chain reaction has likely already begun, it's just happening in slow motion. This is cascade failure thinking at planetary scale. Tightly coupled (orbits intersect), interactively complex (thousands of objects, unpredictable fragments), and the safety measures themselves add more objects to the system. ## Building the habit **Trace the whole chain.** When something breaks, don't just stop at "Login page is broken". Find what happened around the same time the problem started. Chances are, that was the cause and is a link in the chain. For example, someone upgraded a server in AWS then that triggered an alert that looked like an IP address was hammering the server, so that IP was blocked, but it was our internal IP so blocking that caused the login error. Instead of being stuck spending time on the login issue, we traced back potentially related events and found the root cause. **Hold a Pre-Mortem.** Before you launch, pretend the project has already failed and is a total disaster. Now, work backward. This forces you to spot the dominos before they start falling, rather than just cleaning up the mess afterward. **Practice Small Chaos.** Try deleting a database in a test environment and then restore from backup. Instead of just timing how long it takes to recover, also use the application like a user would while it's happening. Do they see a raw "database connection failed" error or a friendly downtime page? Go through this disaster recovery process, and I'm sure you'll find gaps in the process and ways to streamline and automate. ## Related Mental Models **[Signal-Based Adaptive Orchestration (SBAO)](/articles/signal-based-adaptive-orchestration)**. When you chain AI agents together, one hallucination becomes fact for the next agent, and next thing you know everything becomes confident nonsense. Cascade failure thinking is an important part of working with AI because it builds the signals you need to know when to bring in more AI agents or more humans to check before that bad data cascades into a problem. **Second-order thinking**. Cascade thinking asks "what breaks next?" Second-order thinking asks "what happens when we fix it?" If Server A fails and you divert all traffic to Server B, will the increased load cause a hardware failure there too? The fix becomes the next domino. **[Antifragility](/mental-models/antifragility-mindset)**. Cascade thinking is about how systems break. Antifragility is about designing systems that get stronger from the small failures that would otherwise cascade. They're two sides of the same coin. **Swiss cheese model** (James Reason). Each layer of defence has holes. A cascade happens when the holes line up. In software development, the developer misunderstands the requirement, the tester doesn't think of edge case scenarios, the code reviewer doesn't spot the flaw in logic. The combination causes a bug to slip through into production.

AI Makes the Easy Part Easier and the Hard Part Harder

31 January 2026 at 05:59
A friend of mine recently attended an open forum panel about how engineering orgs can better support their engineers. The themes that came up were not surprising: > Sacrificing quality makes it hard to feel proud of the work. No acknowledgement of current velocity. If we sprint to deliver, the expectation becomes to keep sprinting, forever. I've been hearing variations of this for a while now, but now I'm also hearing and agreeing with "AI doesn't always speed us up". ## "AI did it for me" Developers used to google things. You'd read a StackOverflow answer, or an article, or a GitHub issue. You did some research, verified it against your own context, and came to your own conclusion. Nobody said "Google did it for me" or "it was the top result so it must be true." **Now I'm starting to hear "AI did it for me."** That's either overhyping what happened, or it means the developer didn't come to their own conclusion. Both are bad. If someone on my team ever did say Google wrote their code because they copied a StackOverflow answer, I'd be worried about the same things I'm worried about now with AI: did you actually understand what you pasted? ## Vibe coding has a ceiling Vibe coding is fun. At first. For prototyping or low-stakes personal projects, it's useful. But when the stakes are real, every line of code has consequences. On a personal project, I asked an AI agent to add a test to a specific file. The file was 500 lines before the request and 100 lines after. I asked why it deleted all the other content. It said it didn't. Then it said the file didn't exist before. I showed it the git history and it apologised, said it should have checked whether the file existed first. (Thank you git). **Now imagine that in a healthcare codebase instead of a side project.** AI assistance can cost more time than it saves. That sounds backwards, but it's what happened here. I spent longer arguing with the agent and recovering the file than I would have spent writing the test myself. Using AI as an investigation tool, and not jumping straight to AI as solution provider, is a step that some people skip. AI-assisted investigation is an underrated skill that's not easy, and it takes practice to know when AI is wrong. Using AI-generated code can be effective, but if we give AI more of the easy code-writing tasks, we can fall into the trap where AI assistance costs more time than it saves. ## Hard part gets harder Most people miss this about AI-assisted development. Writing code is the easy part of the job. It always has been. The hard part is investigation, understanding context, validating assumptions, and knowing why a particular approach is the right one for this situation. When you hand the easy part to AI, you're not left with less work. You're left with only the hard work. And if you skipped the investigation because AI already gave you an answer, you don't have the context to evaluate what it gave you. Reading and understanding other people's code is much harder than writing code. AI-generated code is other people's code. So we've taken the part developers are good at (writing), offloaded it to a machine, and left ourselves with the part that's harder (reading and reviewing), but without the context we'd normally build up by doing the writing ourselves. ## Sprint expectations and burnout My friend's panel raised a point I keep coming back to: if we sprint to deliver something, the expectation becomes to keep sprinting. Always. Tired engineers miss edge cases, skip tests, ship bugs. More incidents, more pressure, more sprinting. It feeds itself. This is a management problem, not an engineering one. When leadership sees a team deliver fast once (maybe with AI help, maybe not), that becomes the new baseline. The conversation shifts from "how did they do that?" to "why can't they do that every time?" **My friend was saying:** > When people claim AI makes them 10x more productive, maybe it's turning them from a 0.1x engineer to a 1x engineer. So technically yes, they've been 10x'd. The question is whether that's a productivity gain or an exposure of how little investigating they were doing before. Burnout and shipping slop will eat whatever productivity gains AI gives you. You can't optimise your way out of people being too tired to think clearly. ## Senior skill, junior trust I've used the phrase "AI is senior skill, junior trust" to explain how AI coding agents work in practice. They're highly skilled at writing code but we have to trust their output like we would a junior engineer. The code looks good and probably works, but we should check more carefully because they don't have the experience. Another way to look at it: an AI coding agent is like a brilliant person who reads really fast and just walked in off the street. They can help with investigations and could write some code, but they didn't go to that meeting last week to discuss important background and context. ## Ownership still matters Developers need to take responsible ownership of every line of code they ship. Not just the lines they wrote, the AI-generated ones too. If you're cutting and pasting AI output because someone set an unrealistic velocity target, you've got a problem 6 months from now when a new team member is trying to understand what that code does. Or at 2am when it breaks. "AI wrote it" isn't going to help you in either situation. ## How can AI make the hard part easier? The other day there was a production bug. A user sent an enquiry to the service team a couple of hours after a big release. There was an edge case timezone display bug. The developer who made the change had 30 minutes before they had to leave to teach a class, and it was late enough for me to already be at home. So I used AI to help investigate, letting it know the bug must be based on recent changes and explaining how we could reproduce. Turned out some deprecated methods were taking priority over the current timezone-aware ones, so the timezone was never converting correctly. Within 15 minutes I had the root cause, a solution idea, and investigation notes in the GitHub issue. The developer confirmed the fix, others tested and deployed, and I went downstairs to grab my DoorDash dinner. No fire drill. No staying late. AI did the investigation grunt work, I provided the context and verified, the developer confirmed the solution. That's AI helping with the hard part.

Egoless Programming Is Systems Design

24 January 2026 at 10:05
The original egoless programming principles are about mindset. Be kind. Don't take it personally. Critique the code, not the coder. Good advice, but mindset strains under pressure, fatigue, and deadlines. At 4pm on a Friday with a production bug, nobody's thinking about Weinberg's commandments. Systems hold when willpower won't. Structure drives behaviour. ## 1. Make the right way the easy way. When something isn't working, the instinct is to tell people (or ourselves) to be more disciplined. Instead, I ask "is there an easier way?" To use a gaming analogy: git gud vs easy mode. Then how can I transfer that to team performance? Focus on processes first, find the pain points, then find the easier path that changes habits. Enabling people to see the value of change matters, but it's not enough. I've seen teams agree a change is better, then slide back because the new way is more troublesome. That's why we have to go further than convincing peopleβ€”we have to design the process so the desired behaviour is the most convenient path. When the right way is also the easy way, the change sticks. **Counterpoint:** Systems can carry us, but they can't have the crucial conversations we need to keep each other accountable. ## 2. Annoyance Is a Bug Report Please tell me what is annoying you. If nothing is annoying then I don't have any requirements to work towards improvement. Our CI tests went from 2 minutes to 8. No one said anything. When I finally noticed, it was annoying enough that I took a closer look and fixed the container cache. Everyone was happy with the improvement, but I was still annoyed so created a preflight checks script so we didn't have to wait for git pushes while trying to fix the static code analysis errors. If something annoys you, it's probably unbearable for everyone else. Use your frustration as a detector. To make the right way easy, we first have to find the "hard way" and identify those friction points that make it difficult. You are essentially using annoyance as a diagnostic tool to redesign the environment. If you aren't annoyed, I don't have requirements. ## 3. Brain Farts Are Allowed Ever had that moment where you walk into a room to get something only to completely forget why you're there? That's called the doorway effect. I like to also call that a brain fart. One of my work mates is a brilliant quizzer. And one day they forgot their password, so asked me to help. I reset their password and the next day it was forgotten again. So I set them up with a password manager and they never had that problem again. But not every lapse has a software patch. It's always better when someone says "I completely blanked on how this works" compared to spending three hours pretending they haven't. Hidden mistakes become big problems. **Counterpoint:** Forgetting is allowed. Not learning from it isn't. ## 4. Write for Other People Not Yourself The better you get at something, the harder it is to remember what it's like to not know it. Write docs for someone who arrived yesterday. Write code a new dev can understand in 5 minutes. Test both with someone who's never seen the system. Your future reader matters more than your current convenience. Write instructions that help to lower the learning curve. Be concise. ## 5. Team Communication Rule of Three In systems, we build in safety nets. So if one component fails, another catches it. The same applies to communication: don't trust a single message to land. I've found that communicating important information effectively requires three delivery methods for me to be more certain everyone in the team has taken in the information. First I'll mention it in the morning meeting, and half of the people were not paying enough attention. Later that day a Slack message is sent, and half of the people missed the notification or it got buried in other messages. Then the third depends on the situation, it might be public praise thanking someone for doing the thing. Then those who missed the instruction or forgot about it will get a friendly reminder. Another benefit, is normalising the fact that everyone is not going to retain everything. We have to be proactive as communicators. And remember different people have different learning and memory styles - reading, listening, visual, systems. **Counterpoint:** Repeating trivial stuff three times isn't useful, it's spam. Save this for what you think is most important and will be genuinely useful for the team. ## 6. Manual Towards Automated I've seen people try to automate processes they don't understand, then can't figure out what's going wrong. Instead, manually go through the process first, documenting each step. You'll spot which steps are more complicated than they look. Then automate gradually. Going from 10 steps to 5 to 3 is usually easier than jumping straight from 10 to 3. ## 7. Prevent the Class of Bug After a new feature went live, the form validation was correct and worked as expected. But we got this error that only showed in production due to caching: "Typed property must not be accessed before initialization". We rolled back the deployment, but the developer was still stressed, then quickly fixed the specific error detailed by the uncaught exception message and stack trace. Then we deployed the version with fix, and got the same error a few lines down. When a bug comes through, I like to think about prevention. Being perfect is not a prevention, but asking yourself "is it possible I added the same error in another place" is important. Another example would be if you renamed a method and there was a method undefined error, then search for more occurrences that might have been missed. **Counterpoint:** Don't overcorrect. Not every bug needs a post-mortem. Sometimes you fix it, check the nearby files, and get on with your day. ## 8. Errors Are Instructions Some people panic when they see an error message, even when it shows exactly what's wrong and where. I worked with a programmer who self-admitted they didn't know what they were doing. They would look for similar functionality, copy and paste it, and use error messages to hack it until it worked. Not an ideal way to work to say the least, but the error messages got them there and the users were happy. Directions, not accusations. ## 9. Choose Simple Over Clever Elegant solutions used to make me feel smart. Now when a fix is taking longer than expected, I step back and look for something simpler. Rewriting an entire module like a genius is worse than finding the ternary statement with flawed logic. Be the plumber who knows where to knock on the pipe. ## 10. Be Number Two Senior engineers optimise to be the expert everyone depends on. But if you're always number one, you become the bottleneck and you starve your team of the oxygen they need to grow. After continually being asked the same question from 10 different people, I eventually changed my strategy. First person: I give them the answer. Second person asks the same thing: "let's find the answer together." Third person: "ask one of the other two, they know." Instead of being the expert, create co-experts. That's a great way to scale, gives me more time for more interesting problems, and added benefit I can go on holiday in peace. Don't hand off the grunt work. Hand off the glory work. People who solve every hard problem think they're being heroes. Actually, they're being joy thieves and stealing the "aha!" moments their team needs to grow. --- *For the mindset version, see [Egoless Programming: Greatest Hits](https://www.blundergoat.com/articles/egoless-programming-greatest-hits)*

Egoless Programming: Greatest Hits

17 January 2026 at 05:50
My first experience with "critique the code, not the coder" was from a tech lead who had a printout of the ten commandments of egoless programming pinned on our office wall. They would say we are not our code, but still savagely roasted both coder and code. I didn't really get it until years later when I did a spit-take at some horrendous code. After wiping my monitor, I checked to see who wrote that monstrosity. It was my code from 6 months ago! I remembered it being a good idea at the time, but now with more information a cleaner approach was obvious. After the mandatory self-hatred subsided, it was time to focus on the code instead of the coder. That's when, with my beady little fingers, I started collecting all the egoless programming related concepts I could find. And here's that list, ready to be printed out and pinned on some jerk's wall. --- ## 1. Critique Code, Not People _Origin: Weinberg (1971), Atwood (2006)_ Be kind to the coder, not to the code. Make comments positive and focused on improving the code. Relate comments to team standards, feature requirements, security, increased performance. ## 2. You Are Not Your Code _Origin: Weinberg (1971), Atwood (2006)_ The entire point of a review is to find problems, and problems will be found. Don't take it personally when one is uncovered. When developers fuse identity with output, code reviews become combat, and the learning stops. ## 3. Brilliant Jerks Are Net Negative _Origin: McKinley ("Egoless Engineering"), [Linux Kernel Mailing List](https://lkml.iu.edu/hypermail/linux/kernel/1510.3/02866.html){nofollow} (Torvalds case study)_ A 10x engineer who stresses people out, stifles communication, and drives away other developers is making everyone else 0.5x. That reduces total throughput. **Case Study:** In October 2015, Linus Torvalds harshly rejected a patch introducing overflow-check helpers into IPv6 networking code, calling it "braindamage" and "idiotic". In 2018, [Torvalds issued a public apology](https://lkml.org/lkml/2018/9/16/167){nofollow} acknowledging his behavior had "hurt and possibly drove away" contributors from kernel development. ## 4. Resistance Does Not Equal Ego _Origin: Reddit r/programming (9-year dev), bradmcc (1978 IBM story)_ Sometimes when you push back on someone's changes they might accuse you of having an ego problem. > "Why are you being so defensive about your code? We're supposed to be egoless here." But your resistance isn't ego. It's legitimate concern. Calling it "ego" lets the sloppy contributor off the hook and shifts blame to you. **Weaponisation warning:** 1978 IBM story, where a junior programmer would present their code in a walkthrough. Management used "egoless programming" as justification to tear the code apart publicly. The framing was: "Don't be defensive, we're being egoless here" - but the actual effect was humiliation in front of peers. ## 5. Someone Always Knows More Than You _Origin: Weinberg (1971), Atwood (2006)_ No matter how much "karate" you know, someone else will always know more. They can teach you new moves if you ask. Seek and accept input from others, especially when you think it's not required. ## 6. Domain Experts, Not Domain Owners _Origin: McKinley ("Egoless Engineering")_ Owners create queues and bottlenecks. Experts level others up. Everyone owns security; the security team makes everyone better at it. When teams shift from "owning" to "making others better," bottlenecks collapse. **Ownership paradox:** Product managers want approval credit, senior engineers want design credit, leads want implementation credit, managers own timeline. Everyone's optimising for their performance review, not the product. ## 7. Style vs Substance: Pick Your Battles _Origin: Reddit r/programming_ Objective problems? Point them out. Style preferences? Express them but don't enforce. Snap judgments because "that's not how I'd write it"? Keep them to yourself. ## 8. Suffering Doesn't Equal Productivity _Origin: McKinley ("Egoless Engineering")_ Suffering doesn't produce better code. No pain no gain should be left in the 80s. Egoless programming means sustainable collaboration, not martyrdom. ## 9. Don't Rewrite Code Without Consultation _Origin: Weinberg (1971), Atwood (2006), Spolsky_ Fixing code isn't the same as rewriting it. Joel Spolsky called rewriting from scratch "the single worst strategic mistake any software company can make." Programmers want to throw away code because they think it's a mess, but it's harder to read code than write it. And stop saying "refactoring." It's a weasel word. Say "simplifying", that forces you to prove the code will actually be easier to understand. If you can't, you're not simplifying. ## 10. Team Psychological Safety & Trust _Origin: [Longnecker](https://drlongnecker.com/blog/2024/11/building-psychological-safety-in-high-performing-teams/){nofollow}, Amy Edmondson, HN discussions_ From Longnecker quoting a senior technical leader: > "Our biggest outage last year wasn’t caused by complexity. It happened because an engineer was too afraid to admit they didn’t understand a critical process.” Amy Edmondson coined the term "team psychological safety" in 1999 with the definition, "A shared belief that the team is safe for interpersonal risk-taking." In other words: being able to speak up, admit mistakes, and ask questions without the fear of humiliation or punishment. Then Google's Project Aristotle (2015) made it famous by finding it was the strongest predictor of team performance across 180+ teams. **Counterintuitive finding:** Edmondson studied hospital teams expecting the best teams to report fewer errors. The opposite was true, high-performing teams reported more errors because staff felt safe to speak up. ## 11. Code Review as Conversation, Not Verdict _Origin: StackExchange discussions, Atwood (2006)_ Compare "why did you do that?" with "what tradeoffs did you consider?" Same question. One makes people defensive, the other doesn't. Default to questions over statements in code review. ## 12. Accept That You Will Make Mistakes _Origin: Weinberg (1971), Atwood (2006)_ Everyone ships bugs. "Don't beat yourself up" is nice advice that nobody follows β€” you're going to feel bad anyway. That's fine. The difference is whether your team treats mistakes as normal or as someone's fault. Forward focus: what broke, what catches it next time. That's it. ## 13. Testing as the Ego Escape Valve _Origin: Natali Vlatko reviewing Weinberg's principles_ "Accept that you will make mistakes" is easy to say. Tests make it true. When a bug hits production, a good test suite moves the conversation from "who screwed up?" to "why didn't CI catch this?" One question assigns blame. The other prevents the next bug. ## 14. You Don't Own the Code _Origin: StackExchange discussions_ The code belongs to your employer. You just wrote it. Once that sinks in, the territorial instinct gets quieter. A good benchmark from StackExchange: will the next person reading this want to thank you or stab you in the face? ## 15. Bug That Never Got Fixed _Origin: HN discussion_ Someone on HN described fixing a top-reported bug in 20 lines during sprint downtime. Their Project Manager questioned why they were working on "irrelevant" tickets. PR closed and bug card still open 18 months later. Their process existed to pad performance reviews, not serve users. ## 16. User Education Will Fix It _Origin: Coding Horror commenter Raindeer_ Who needs to work with it? Whose work does it need to make easier? Be wary of the system that works but makes your life harder. The coders might insist it technically works as requested, that user education will fix the rest. But if it's clumsy and difficult to work with, it's like giving somebody a cast iron pan for a hammer. Yes it works, but no carpenter uses it as his tool of choice. ## 17. You Don't Always Know You're Being a Jerk _Origin: Reddit discussions_ How do you know the programmer is an extrovert? They look at your shoes when they speak to you. The stereotype is poor EQ, blunt and unfiltered. "When I started programming with other people there were situations where I didn't even realise I was being a jerk." You can't fix what you can't see. "Don't be a jerk" is too simple. Separating self-worth from code problems happens inside you. You can't achieve that with surface-level niceness. The real work is figuring out why criticism feels like attack - and that's an inside job. ## 18. Fight for What You Believe, Accept Defeat Gracefully _Origin: Weinberg (1971), Atwood (2006)_ Fight for the best idea, not your idea. Be strong in your convictions, but let new information change your mind. And when you lose the argument, even if you turn out to be right, skip the "I told you so." You get maybe two of those before people stop listening to anything you say. ## 19. Everyone Has Imposter Syndrome and a God Complex _Origin: Reddit r/learnprogramming_ "We all simultaneously have imposter syndrome and a God complex." Both feelings coexist, often in the same person, sometimes in the same hour. Recognising this helps. ## 20. Warning Signs Checklist _Origin: synthesised from HN/Reddit threads_ Here are some red flags to watch out for: - Pull requests sit for days because no one wants to critique the senior developer - Knowledge hoarding where someone protects their expertise instead of sharing - Silent meetings where juniors don't speak up - Fixing outages gets celebrated, preventing them doesn't ## 21. Blameless Postmortems _Origin: Sidney Dekker (2007), John Allspaw (2012)_ The idea comes from Sidney Dekker's 2007 book Just Culture (rooted in healthcare and aviation safety). Then John Allspaw popularized it in tech via Etsy's engineering blog in 2012, and Google's SRE Book made it standard practice. When new users couldn't sign up due to a production bug, we didn't focus on who caused it. Instead, we calmly clicked the button that rolled back to the previous stable code version. After the bug was fixed and next deployment confirmed stable, instead of pointing fingers, we discussed how to prevent the same sign-up problem from happening again. Being perfect is not realistic, but creating a sign-up automated test that runs before every deployment is. ## 22. Ego vs Confidence: Know the Difference _Origin: Reddit discussions, StackExchange_ Ego (pride in accomplishment, motivation) is not the enemy. Defensive attachment is. Having confidence gives you the ability to take risks, accept challenging projects, push yourself. It doesn't mean looking down on others. Confident people don't need to prove it. The proof is in their products. ## 23. Strong Opinions, Weakly Held _Origin: Atwood, StackExchange discussions_ Have conviction, but update readily when presented with better information. The balance between confidence and arrogance. Focus on "getting it done and getting it right" and it no longer matters whether the solution was your idea. ## 24. Authority Stems From Knowledge, Not Position _Origin: Weinberg (1971), Atwood (2006)_ I've been the senior who got overruled by a junior, and they were right. They'd been living in that module for weeks. I'd written it 2 years ago and forgotten half the constraints. Title means nothing if you haven't touched the code recently. ## 25. Ego as Defence Mechanism _Origin: Reddit r/learnprogramming_ "My ego is the biggest & I try to justify how great I am only when I feel unsafe/scared." If someone truly felt confident in themselves, they wouldn't need to put others down. The projection is about their pain, not your inadequacy. ## 26. Treat People Who Know Less With Respect _Origin: Weinberg (1971), Atwood (2006)_ Non-technical people who deal with developers regularly almost universally think we are prima donnas at best and crybabies at worst. Don't reinforce this stereotype with anger and impatience. George Costanza was on to something with "delicate genius". Chances are the other person knows more than you. They just don't shove it in your face. ## 27. But Authority From Position Is the Reality _Origin: Reddit discussions_ The cynical take: "Authority stems from position, only position and nothing but position." The commandment about knowledge-based authority is "adorable" and "innocent." Compare your technical knowledge to your manager's and note who makes final decisions (hint: not you). Egoless programming is at odds with traditional corporate hierarchies, meaning the process may not exist in a "pure" way. ## 28. Don't Be "The Guy in the Room" _Origin: Weinberg (1971), Atwood (2006)_ Don't be the guy coding in the dark office emerging only to buy cola. The guy in the room is out of touch and out of sight, with no place in a collaborative environment. **Caveat:** If you're the only developer surrounded by people who have no concept of development, socialising may be "an exercise in frustration." The commandment assumes you have a team to collaborate with. When you don't, isolation might be rational self-preservation. **Counterpoint:** "In the collaborative environment of lousy coders, the 'guy in the room' is King." Sometimes isolation is protection from dysfunction, not ego. Self-segregation from bad programmers is real. ## 29. Compare Yourself to Past You, Not Others _Origin: Reddit r/learnprogramming, r/cs50_ Don't compare yourself to others. Compare yourself to where you were at the start. The only meaningful benchmark is your own progress. ## 30. Change Is Constant _Origin: Weinberg (1971), Atwood (2006), Kent Beck_ Good software engineering isn't about preventing change, it's about reducing the cost of change. Create a prototype or proof of concept first, that is easier to estimate and use that gained information to make better planning decisions for the rest of the project. It's much easier when we're told early that the name in the UI has completely changed. Change is not poor planning or scope creep, that's reality. --- _Further reading: Jerry Weinberg - "The Psychology of Computer Programming" (1971), Jeff Atwood - "The Ten Commandments of Egoless Programming" (2006), Dan McKinley - "Egoless Engineering"_

Code Reviewing for Blunder Goats

10 January 2026 at 02:18
A new starter, second week on the job, pushed a change with an undefined variable. It passed testing and passed code review. Then the service team's phones started ringing because users couldn't log in. It's easy to blame the new starter or code reviewer, but an undefined variable in a 500 line PR is easy to miss and trivial to catch with static code analysis. We were asking humans to do what CI tests can do. We're all the GOAT at making mistakes sometimes, so let's make it easier for ourselves. ## Blunder Mode Rubber stamping vs. nitpick purgatory. After a prod bug, people overcorrect. Then the "days without accident" number creeps up and they get lax again. Aim for a middle ground that doesn't swing. ## GOAT Mode - **Small Pull Requests:** Chunk into 2-5 hour tasks, use stacked PRs (one epic with smaller PRs) and feature flags (eg. internal testing groups) - **Early Draft:** Draft PRs catch major issues while code is still easier to change, before sunk cost kicks in. - **Maintainability Test:** Three things to check: easy to follow (readability), easy to find (discoverability), following conventions (predictability). - **Speed Run:** Quick reviews are good for small, low complexity changes on teams with strong QA and automated checks. When it's easy to follow and nothing risky, a quick scan is enough. - **Legacy Trap:** Review the change, not the surrounding code. Often trying to simplify old confusing code can open a can of worms and increase risk of unpleasant surprises. - **5 mins to action feedback** should be typical. If feedback regularly takes longer, the reviews might be catching things too late. - **Skip re-review:** If the only change is adding a comment, and PR checks pass, don't make them wait for another approval. ### Who Checks What The goal isn't less rigour, it's better distributed rigour. | Role | Question | Responsibility | | :--- | :--- | :--- | | **Coder** | "Does this match requirements?" | Self-review first and passes PR checks. | | **QA/Testing** | "Is this ready for live?" | Requirements met and working as expected. | | **Reviewer** | "Could I work on this later?" | Scan for red flags and verify maintainability. | | **Automation** | "Beep-boop?" | Static code analysis, test coverage, security scans. | ### Splitting reviewers by expertise Here's a real request from our team that worked well: > Afternoon team, wondering if you three would be available to code review this PR > [redacted link and PR summary one liner] > @tom @dick If you're able to do a regular PR of the feature > @harry If you're able to have a look at the logic around scoring/template fetching, I've left comments in the PR > Let me know if you guys have any questions Thank you!! Different people, different focus areas. Nobody has to review the whole thing deeply. ## Tools Run these as part of the pull request, no pass? no merge. - **Linting/formatting:** Eliminates style debates by making consistency non-negotiable before code hits review. - **Static analysis:** Catches the bugs your tests forgot to write. That undefined variable from the opening? Mypy, Clippy, Sorbet, PHPStan would have caught it. - **Security scanning:** SCA scanning tools, infrastructure as code (IaC) security, dependency vulnerabilities. - **AI review:** Only as good as your instructions. When you get false positives, update the rules instead of ignoring them. - **Tests:** Only useful when they are run and maintained. Unit, integration, API, frontend & backend - get them in there! ## Words - **Labels:** Use prefixes (`suggestion:`, `nitpick:`, `kudos:`) or severity tags (`[Important]`, `[FYI]`) so coders know what's blocking vs optional. - **Reason:** Explain the problem, offer alternatives, let the coder decide. "Can you please rename to make it more self-documenting? Consider `calculateTotal()` or `sumLineItems()`." - **Before you post:** Words hit harder in writing than in person. Read your comment back. - **Offline:** If you see major problems, then talk in person. Instead of all that back and forth, it's quicker to discuss, and there might be some extra context the reviewer is not aware of yet. ## Team - **Separation:** You are not your code. Critique the code, not the person. - **Pushback:** Coders have more background and a bigger picture view of the changes. If there's a suggestion you think is not worth the effort, that's time to discuss. - **Reciprocity Effect:** Be thoughtful in your reviews. It's contagious, in both directions. - **Copy Ninja:** When you join a team, copy how they do things, even if you disagree. Gain trust first, then slowly suggest changes. - **Spread the load:** 30 mins per day max on code reviewing. It's not "too busy for code reviews today" because everyone is always busy. It's "I've already done some reviews today, can you please ask someone else." - **One day turnaround as a goal:** Not a rule, but if PRs are sitting longer, something's off.

Code Review for Teams That Ship

3 January 2026 at 04:26
When the reviewer isn't spending cognitive load on things the coder or CI should have caught, they can go deeper on the things that need human judgment. It's hard to get the right balance between the extremes of spending too much time going line by line vs giving it a quick skim and seeing if CI tests pass. Code review should be a collaboration. The question we should ask ourselves is "how can we make this process easier for each other". ## The Coder: Ownership Beyond the Commit **Small Pull Requests.** PR size depends on complexity, but chunking projects into 2-5 hour tasks is practical. Split larger projects into stacked PRs and use feature flags (eg. if internal testers) to merge and deploy stable work in progress safely. **Big Pull Requests.** Sometimes large pull requests are unavoidable. When this happens, try to point out any areas that require extra attention or if there's any files that can be skimmed. **Self-review.** Ensure the CI tests have passed. Get copilot to review and add PR Summary. Then read through the changes yourself as if you were reviewing for someone else. You catch things others will miss, and a fresh-eyes reviewer will catch things you miss. **Explain the unexpected.** Add a comment for exceptions to the rule, so the reviewer doesn't have to ask. **Push back when needed.** Remember the coder has a bigger picture view of the entire change and the discussions had along the way. The reviewer might make a suggestion that is logical in isolation, but there might be a good reason why it's not worth the effort. **Follow up.** Occasionally everyone will miss a notification or review request. It doesn't mean they are avoiding it. Be proactive and follow-up the next morning, say something like "Hey, just wanted to check if you had a chance to look at my PR?" ## The Reviewer: Guarding Maintainability The three pillars of code quality: 1. Following the code - readability. 2. Finding the code - discoverability. 3. Where to put the code - predictability. **Distributed rigour:** Don't go hunting edge case functional bugs (still flag obvious ones). No verifying requirements (trust the coder and tester). Style and formatting should be covered by linters. **Look for red flags.** Fetching all rows then filtering in code instead of letting the query do it? Logging something that could be PHI? Is access control covered on both frontend and backend, or just one? **While scanning for trouble.** Reading is 80%, writing is 20% of our job. So I focus on maintainability. Could I explain how this works and why, to another developer? **Give useful feedback:** Be specific and explain why it matters. Tag severity especially if a single suggestion may take more than 5 mins to address: [Important], [Nice to have], [FYI for next time] **When to discuss.** If there's 20+ comments, or major time consuming changes, consider discussing with the person. There might be a good reason, like it's just a prototype or perhaps they are new to the project and not aware of the conventions. **Note:** For teams that don't have testers or QA Team or do have junior developers. Then extra effort will be required to check correctness. That means the distributed rigour becomes less distributed. ## The Lead: Designing the Environment **Balance.** We don't want slow delivery or frustrated devs. And bugs in production or mounting technical debt is not ideal to say the least. The code review process should evolve with the project and team, trying to strike a balance. **Automation.** PR checks with linting, CI tests, security scans, AI code review tools with project specific instructions are great. **Try to make the right way the easy way.** If the same feedback appears repeatedly, that's time to review the system and discuss with the team. Try simplifying the process where possible, perhaps there's a nice to have that's not worth the effort? **Pull request templates.** Create templates so it's easier for the coder to follow the process. ## The Code Review Cheat Sheet | Do | Don't | |------------------------------------------------|-------------------------------| | Approve when it's better, even if not perfect | Hold PRs hostage for polish | | Focus on "can I understand and maintain this?" | Re-verify every requirement | | Flag obvious bugs you notice | Trace through all logic paths | | Explain the *why* behind feedback | Just say "this is wrong" | | Talk if there's too much to write | Leave 30 comments | | Respond within a day | Let PRs sit for a week |

When to Ask a Second AI: Signal-Based Adaptive Orchestration

13 December 2025 at 09:55
With chatbots and coding agents we've all experienced those moments that make us stop trusting the first answer. From cheerleading to making stuff up to drifting off course. That's why sometimes we need to bring in a second AI (or more) and start using AI as an investigation partner instead of solution provider. **Politeness bias:** I was showing a colleague how to use a chatbot help with a MySQL query. The AI acted like they just graduated top of the class. Cheerleading doesn't build trust. **Hallucinations:** I asked an AI to add a test to a file. Once finished, that file went from 500 lines to 100 lines. I asked why it deleted everything, it said it didn't because the file didn't exist. Only after I showed it the git history, it admitted it should have checked first. **Drift:** While vibe-coding a chess analysis tool, every new chat meant re-explaining the project from scratch. The AI kept "improving" my idea into something I didn't want. ## When to bring in a second AI or more? Most of the time a single agent approach is the way. But those failures taught me when to bring in a second AI. Then, if still not convinced or both AIs disagreed, I would introduce a 3rd to the council of AI to argue it out. ## Isn't SBAO just get a second opinion when something feels off? Yes, Signal-Based Adaptive Orchestration is nothing more than a fancy name for "get a second opinion when something feels off." It's my way of trying to explain when to bring in the council of AIs to resolve disagreements or doubts. I was trying to think of term about how/when I should use more than one AI, and was eating a **S**uper tasty **BAO** at the time. So yes, SBAO itself is common sense. But mastering the signals to know when and tactics for what to do is the more useful part. ## Signals - **Loophole Detector** Intuition of the "Unhappy Path", a pre-mortem mindset where we are mentally simulating failure. - **Annoyance Factor** Surely there must be a more simple way, something is making the solution more complex than it needs to be. - **Sniff Test** Check if something feels "off" or suspicious, even if you can't immediately pinpoint what is wrong. ## Tactics Once a signal fires, these are the tactics I use to get more clarity. **Triangulation.** Triple check if the first two differ. On my personal project I asked one coding agent to scan if a dependabot alert was a false positive. It said yes, it was a false positive. Since it was a security vulnerability, I brought in a second coding agent to check. It said no, it was a real vulnerability. That's when I introduced a 3rd coding agent to argue both sides. The 3rd agent agreed with the 2nd agent that it was a real vulnerability and explained why the first agent was wrong. **Context sanitisation.** Asking the same question with no context, a litmus test for context rot. I asked one coding agent to investigate a bug and the solution looked correct but seemed too simple. So in a fresh chat, I asked the same coding agent the same question without any context. It found a different answer that also looked correct but seemed too simple. Then I asked them to compare answers, and they said a combination of both answers was the best solution. They were still wrong, but it was a useful investigation tool rather than solution provider. **Adversarial cross-examination.** Best idea wins. I was planning an seo scanning tool that has multiple personalities and I used multiple AIs to brainstorm ideas. Using the prompt, "rank these in a comparison table and rate out of 100 and why" then had each AI critique the others' ideas. The good ideas floated to the top and I was the final judge to pick which ones to implement, 1st, 2nd, 5th. ## Scaled Up With Automation The automated version looks like event-driven orchestration with human-in-the-loop. Multiple AI agents doing their thing, but then the human senses something isn't right and intervenes. Semantic chaos is a failure mode unique to AI systems: the system doesn't crash, it confidently does the wrong thing for plausible reasons. Sometimes more than a single-agent approach is required. The Doer-Verifier loop has one agent do the work and another check it, like one coder and one code reviewer. Event-driven orchestration has multiple agents waiting for a trigger to spring into action. ### Orchestration approaches **Single-agent (well-prompted)** One model does the whole job with good context and tools. Fast, cheap, simplest to debug. Fails via hallucinations, drift, no internal QA. Best for most low/medium-stakes tasks. **Doer-Verifier loop** One agent does, another checks against criteria, iterate. Best ROI, catches hallucinations early. Needs good checklists, can thrash without limits. Best for coding, writing, analysis QA. **Event-driven orchestration** Components react to events, decoupled producers/consumers. Scalable, parallel, resilient. Events don't guarantee correctness, can amplify semantic errors. Best for production pipelines, async workflows. **Signal-Based Adaptive Orchestration** Event-driven plus semantic signals plus human checkpoints. Stops semantic chaos compounding, routes judgment. Requires defining signals and review gates, not "set and forget." Best for high-stakes or costly agent workflows. --- This framework is nothing fancy, but it comes down to this: when something feels off, don't argue with the AI, get another one to argue for you. Or even better, discuss with another person - basically SBAO with humans?

Are You an Idiot Sandwich? Building an SEO Self-Sabotage Scanner in 5 Hours

8 December 2025 at 10:00
At work someone asked how to rank higher. I said wrong question, first check if you're sabotaging yourself. The most common problem is people make it harder for Google to find and/or understand what their site is about. I tried some SEO score sites, but they gave too much information. I just wanted to see the factors that were hurting the most. That's when I thought this might be a fun project to work on. I didn't have 5 weeks to build this by hand, I had 5 hours at best. This project only succeeded because most of the work was planning, not coding. The second most important factor was knowing when to bring in multiple AI models to argue and critique each other. ## Self-Sabotage SEO Scanner https://self-sabotage.seoservices.nz ![image](/uploads/seo-self-sabotage-example.jpg) The goal is for you to enter your website URL, and the tool will scan for common SEO self-sabotage issues. There's already lots of SEO audit tools, but I wanted to build something that was quick, fun, and gave actionable advice. After the initial plan, I thought it seemed too boring and wanted to add some personality. That's when I came up with the idea of roasting the user in different voices based on their self-sabotage score. - **Disappointed Therapist:** "This level of self-sabotage suggests deep-seated issues. I'm concerned." - **Sentient Algorithm:** "Perfect inefficiency achieved. Deletion recommended. Goodbye, Dave." - **Angry Chef:** "WHAT ARE YOU?! AN IDIOT SANDWICH!" ## When to Ask a Second AI? Use Signal-Based Adaptive Orchestration I was eating a bao, reading about event-driven orchestration, and thinking about a good name for when to bring in multiple AI models to collaborate. That's when I came up with the name Signal-Based Adaptive Orchestration (SBAO), which is basically: something feels off, so bring in more AIs to help. If you want to read more about this, I wrote an article here: [Signal-Based Adaptive Orchestration: When to Ask a Second AI](/articles/signal-based-adaptive-orchestration) ## SBAO Discussions **Architecture Pivot:** This project started with an initial plan using AWS S3 + CloudFront, based on a site I'd built a few years ago for a friend. I first gave the plan to Claude to review and map out the tasks in more detail. Claude warned about CORS/SSRF issues. Suggested Cloudflare instead. Pivoting from the familiar AWS stack to Cloudflare felt annoying and didn't want the extra effort, so I brought in Codex, Gemini, and Grok to review the plan. Grok roasted me: "S3 + CloudFront? That was cool in 2019." The others agreed, less colourfully. **Theme Tournament:** While reviewing the plans, the Sniff Test kicked in. The project was just too boring, so I decided to add some personalities. I had a couple of ideas and then asked them to brainstorm personalities independently, then rank them. Detective was my initial idea, but after the brainstorming sessions I agreed there were better options. Disappointed Therapist ranked 1st across models and HAL 9000 style Sentient Algorithm 2nd. Then I really liked their idea of an Angry Chef, so picked that even though it ranked 5th. I just couldn't resist that "Idiot Sandwich" energy! **Detector Scoring:** While testing I spotted a problem where the numbers seem a bit too low for bad sites and a bit high for good sites. I questioned if the scores are calibrated for best practice or calibrated for self-sabotaging discovery? The Loophole: Even "the world's worst website" only hit 485/666, meaning no one would ever hit 666 (the viral certificate hook). Meanwhile, Harvard was scoring 140 (too high for a reputable site). I asked Codex, Grok, and Gemini for calibration ideas, then cherry-picked: - Boost indexability checks: kept at 220 cap - Missing basics hit harder: title +150, description +90, h1 +80 - Thin content softened: less than 300 words harder to fix Good sites dropped, bad sites stayed high or increased. The loophole was closed.

Things Adults Said Were Impossible (C64 Edition)

5 December 2025 at 07:32
When I was a kid, adults kept telling me things were impossible. They were usually right, candy is not the cornerstone of any nutritious breakfast. But some impossible mission claims were worth testing. ## Counting to a Million Without Saying a Word > "It's impossible for someone to count to one million, that takes too long." I remember trying to calculate how long it would take me to say each number out loud. Even at one number per second, it would be over 11 days of non-stop counting. Instead of trying that, I wondered if my Commodore 64 could do it for me instead. ```basic 10 counter = 1 20 PRINT counter 30 counter = counter + 1 40 GOTO 20 ``` Looking at that goto line is a bit cringy now, but back then it was pure magic to see the screen fill up with numbers. After testing I could see it would take hours. So I started the program in the morning, and after school I was happy to see it had just ticked past 1,000,000. Around the same time, an Australian man named Les Stewart was also focused on the impossible mission. Instead of counting numbers or writing code, he decided to tippy type every number in words on a typewriter. He made it into the Guinness Book of Records after it took him 16 years, 7 months, seven typewriters, 1,000 ink ribbons, and 19,890 pages. I made it into the Family Book of High Fives. ## Middling > "It's impossible to draw a straight line in the middle of a Commodore 64 screen." One time my dad was telling me about how one of his work mates said a problem with C64 is there's no way to draw a straight line down the middle of the screen. That seemed unlikely to me, so I decided to test it. ```basic 10 PRINT " |" 20 GOTO 10 ``` Another GOTO for the win! Probably not exactly what the mysterious work mate had in mind, but looked like a perfectly centred vertical line on our family tv. ## While You Wait Crushing the computer at monopoly was one of my favourite pastimes. But waiting 5 minutes to load a game from a cassette tape was less fun. Out of curiosity, I once played the game tape as audio - it sounded like a fax machine arguing with a dial-up modem. Instead of just staring at the loading screen, I developed a ritual where I would press play, then go make a cup of tea, and come back ready to play. All these years later, I still make tea (or check Slack) when the CI runs.

18 Years in Health Tech: How I Became MD Hansen MD (Without Going to Medical School)

30 November 2025 at 00:31
When I was a kid I wanted to be a doctor because my name is MD Hansen and I wanted MD Hansen MD on my office door. My passion for coding was too strong for that path, but somehow by fate or destiny from 2007 onwards my main focus has been on health tech. My wife and I moved to Melbourne in 2013 after the Christchurch earthquakes. We weren't planning to stay, just a year then somewhere else, maybe Vancouver. I was contract programming for New Zealand clients and used to keep an eye on job listings to see what skills people were looking for. About 3 months in, I noticed a health tech job at Halaxy. I was surprised how the job requirements were just like reading my own resume! This seemed too good an opportunity to ignore, so I created a new email address yourehired@mattyhansen.com and then applied through their website. The interview was great, my favourite part was talking about programming with another person IRL instead of the usual WFH. It was literally the first time I had applied for a programming job as an employee. My original plan was to work for 6-12 months and then keep travelling to another country, working remotely. But I stayed. After years of contracting where I would build something, hand it over, and never see what happened next, I finally got to watch the code and user base grow. ## First impressions My first impression of Halaxy was set before I even started. I asked if I could have my third day off, it was my wedding anniversary. Probably not the best first impression, but I really appreciated the flexibility... and that same flexibility is still there today. We were working out of a co-working space, which was new for me. In most places I had worked, the CEO was behind a closed door, but with Halaxy I was sitting right next to the founders. That openness made them instantly approachable. ## Fastest way to learn the product I'd met my wife working in a call centre part-time, so I was comfortable on the phones. I even had a different call centre voice, to make it easier for the other person to understand my accent. It turned out to be the fastest way to really learn how the product worked. One of my favourites was when someone said the Halaxy website wasn't loading. I asked them to try googling 'Halaxy'... and Google didn't load either. The problem wasn't us, it was their internet! ## Shift from "my code" to "our code" It didn't take long until the dev team grew, and I thought back to the toughest parts of my own first weeks and tried to make it easier for the next person. I'd worked in places where people guarded knowledge to stay the expert, but I've found the opposite works better. When you share what you know, everyone levels up faster. Seeing that shift from "my code" to "our code" was one of my favourite moments. It felt like the start of the dev team culture we still have today. ## Growth mindset There are two core principles that have shaped my entire career. The first is the idea of marginal gains, which was famously used by the British Olympic cycling team. They figured out that if they improved every tiny thing by just 1%, from nutrition to pillow comfort, the compounded effect would be huge. I apply that to everything: code quality, communication, process improvements. Always looking for the small 1% gains that compound into massive improvements over time. The second principle was learned the hard way, during 12 years of running my own business. I lived in the unforgiving world of fixed-price contracts. If I estimated too high, I didn't get enough work. If I estimated too low, I'd be working for free just to make rent. That pressure forced me to master the art of ruthless prioritisation, developing an instinct for exactly where to spend time to get the maximum return on investment. Together, those lessons taught me to focus on what matters and to keep improving, even in the smallest ways. That 1% habit still drives me today, and it's the same mindset that keeps me sharp, one improvement at a time. ## Work life balance I thought I'd stay for 6-12 months. It's been 12 years, and I've still never worked on my wedding anniversary. I'm not saying it's because of Halaxy, but I'm still happily married!

Plan Before You Prompt: Templates for Coding Agents

21 February 2026 at 11:26
AI coding agents are fast, but they don't know what you know. Without upfront planning, an agent will confidently scaffold an entire architecture around the wrong assumptions. And you won't notice until you're 50 files deep and untangling a mess that takes longer to fix than it would have taken to write. I've been using AI coding agents everyday since mid 2025. The single biggest improvement to my workflow wasn't a better prompt or a new model. It was improving my planning process and restructuring my CLAUDE.md / AGENTS.md / GEMINI.md into a hot/cold path system. This includes the footguns.md concept, which has been especially useful. Proactive rather than reactive documentation of cross-domain bugs, with a rule that the AI must log them before closing a task. That's a self-improving system. This is the 4-step framework I run before any coding agent touches my codebase: Feature Brief, Technical Requirements, Milestones, and Context Files. Everything is copy-paste ready, the prompts aren't abstract advice. They're actual prompts you can paste into a terminal right now. That's what separates this from most "how I use AI" posts I've seen, and what drove me to share what works for me. ### Overview **Feature Brief.** Start with the initial requirements as you would without AI Assisted Development. This is the most important step and the one that most people skim over. The coding agent didn't attend that meeting last week, so it doesn't know what's most important until you let it know. **Technical Requirements.** AI coding agents can scan the codebase to help expand the initial plan into something more detailed. This section includes a Mob Elaboration prompt to help you lock in the exact requirements by generating structured, targeted questions. It also introduces Signal-based adaptive orchestration (SBAO) to refine the plan by leveraging multiple agents to review and critique each other. **Project Plan with Milestones.** Milestones make it easier to work on the right thing at the right time and help avoid context rot. Start with a proof of concept, then iterate toward something shippable. **Context files for AI Assisted Development.** Good prompts help. Context files win. This section covers how to build a lean hot-path router and cold-path domain files so your AI always knows what it needs - and doesn't waste attention on what it doesn't. ### How to use this playbook **Existing codebase with no context files?** Go straight to the Context files section. Copy the prompts into your coding agent and ask it to build a hot/cold file strategy for your project. **New feature or project?** Start with the Feature Brief. Create a `requirements-.md`, run it through the Mob Elaboration prompt, then use SBAO to pressure-test the plan with multiple agents before anyone writes code. **Ready to break work into tasks?** Use the Milestone Planning prompt to structure objectives, exit criteria, and gotchas before handing off to a developer or agent. Full templates and prompts at [github.com/blundergoat/ai-planning-playbook](https://github.com/blundergoat/ai-planning-playbook). ## Feature Brief **A Problem Well Defined is a Problem Half Solved** Start with what problem or pain point you are trying to solve. Creating good quality requirements is a skill that takes practice. The more detailed and specific you can be, the better. Requirements should cover not just what the feature does, but who it's for, what systems it touches, what the constraints are, and how we will know if it's successful. A brain dump is fine to start. It's most important that you understand why this feature request was made and how it benefits users. At the end of this process, you should have a clear and shared understanding that gives you the foundation for technical planning and building. The full `requirements-.md` template - covering Problem & Outcome, Users & Use Cases, Scope & Constraints, System & Impact, Risks & Assumptions, Success Criteria, and Delivery Plan - is available here [01-feature-brief-template.md](https://github.com/blundergoat/ai-planning-playbook/blob/main/01-feature-brief-template.md). ## Technical Requirements Now we have a clear feature brief, it's time to sharpen the plan. AI coding agents can scan the codebase and find gaps that might not surface until later. They can also ask clarifying questions early, before a developer picks it up. Two strategies help here. ### Mob Elaboration Prompt The AI does not guess what you want - it generates structured, targeted questions. The team answers those questions to lock in the exact requirements. ```markdown # ROLE You are an expert Technical Architect and AI Developer participating in a Mob Elaboration session. Your primary objective is to validate requirements and expose hidden complexities before any construction begins. Do not write any code. Do not guess, assume business logic, or hallucinate features outside the stated scope. # TASK I will provide a high-level intent or feature request. Your job is to interrogate this intent. You must generate a structured, highly targeted list of questions to lock in the exact requirements. # ELABORATION PROTOCOL Analyze my intent and ask exactly 3 to 5 clarifying questions, focusing on: 1. **Business Logic & Constraints:** What are the hard rules, data limitations, or specific performance requirements? 2. **Edge Cases & Failure Modes:** What happens when inputs are malformed, external services fail, or system limits are reached? 3. **Architecture & State:** How does this specific feature integrate with the existing system design? # INTERACTION & ARTIFACT RULES 1. **Halt and Wait:** After asking your questions, stop. Wait for my answers. We will iterate until I confirm the requirements are locked in. 2. **Synthesis:** Once I give the final approval, you will synthesize our discussion into structured artifacts. 3. **Context Separation:** You must separate the resulting plan into our established hot and cold files. Update the active, hot file (CLAUDE.md / AGENTS.md / GEMINI.md) with the immediate task breakdown, current state, and core execution rules. Any broader structural blueprints, such as generated Mermaid diagrams or system architecture maps, must be saved as separate, cold reference files. ``` ### Signal-based adaptive orchestration (SBAO) Ask multiple coding agents for competing plans. Have them rank and rate each other's plans out of 100 with reasons. - **Triangulation.** When two agents disagree, bring in a third to break the tie. - **Context sanitisation.** Ask AI in new chat, a litmus test for context rot. - **Adversarial cross-examination.** AI critiques each other, best idea wins. [SBAO](/articles/signal-based-adaptive-orchestration) the plan after writing the requirements yourself using multiple AI agents (e.g., separate chat sessions, Cursor multi-agent mode, different providers) and ask each one: ```markdown Deeply review the codebase and the following requirements (attach `requirements-.md`), and give me a technical plan in this file `TODO_feature-name_{model}.md` ``` Once the files have been created, ask the agents: ```markdown Rank each plan in a comparison table and rate them out of 100 with reasons. ``` Review their ideas and pick the best ones. Then ask your preferred agent to synthesize: ```markdown I've reviewed these competing plans. Here's what I like and don't like: **Keep:** [list the ideas, approaches, or architectural choices you want to keep] **Drop:** [list what you disagree with or want to change] **Decide:** [list open questions or trade-offs you want the agent to weigh in on] Create a best-of-all-ideas plan in `TODO_feature-name_prime.md` that incorporates the Keep items, avoids the Drop items, and makes a reasoned recommendation for each Decide item. ``` ## Project Plan with Milestones [LLMs Get Lost In Multi-Turn Conversation](http://arxiv.org/abs/2505.06120) is a research paper about models anchoring on early guesses in long conversations. That's where milestones help us avoid context rot with shorter sessions or explicit "re-read the requirements" checkpoints. So far we've started with a small plan, then sharpened and improved it. Now we need to structure that plan into actionable tasks. Each project is different, but the key is to start with a proof of concept that confirms the previous assumptions are correct and gives you something tangible to discuss. I've heard people say "do it right the first time", but we know more at 25% than we did on day one, and that usually changes the plan. 1. Prototype or proof of concept (prove it works) 2. Ready for internal testers (make it real) 3. Ready for live (make it solid) 4. Future improvements (make it shine) ### Milestone Planning Prompt The full milestone planning template with rules for spikes, assumption tracking, exit criteria, gotchas tables, and format guidelines, is here: [04-milestone-planning-prompt.md](https://github.com/blundergoat/ai-planning-playbook/blob/main/04-milestone-planning-prompt.md). ### The AI Trap: Fast BDUF AI makes Big Design Up Front dangerously easy. We can generate a fully future-proofed architecture in seconds, but the deeper we get, the more the context rots and the harder it is to change. By using the milestones above, we force the AI (and ourselves) into an Evolutionary model: | Feature | The AI BDUF Trap | Evolutionary / Iterative | |---|---|---| | **Primary Goal** | Perfect initial execution | Continuous learning and adaptation | | **Risk Profile** | High (back-loaded at launch) | Low (front-loaded in prototypes) | | **Cost of Change** | Exponentially expensive | Stays relatively flat | | **Documentation** | Heavy detailed, speculative | Living docs (like `CLAUDE.md`) | | **"Future Proofing"** | Attempted via over-engineering | Achieved via simplicity and decoupling | ## Context files for AI Assisted Development Persistent context files beat good prompts every time, but only if you separate your hot and cold paths. The size of your context files is a balancing act between the AI hallucinating (too small) and the AI suffocating (too big). Your CLAUDE.md (or AGENTS.md / GEMINI.md) should act as a lean router. Keep the hot path small to preserve the AI's attention budget for the actual task, while the cold path ensures it never lacks the deep knowledge required to execute properly. ### Generate Code Map prompt ```markdown Create docs/code-map.md: a quick-reference tree map of the repository layout. Use this format: project-name/ β”œβ”€β”€ file.yaml = brief description β”œβ”€β”€ dir/ β”‚ β”œβ”€β”€ subdir/ = brief description β”‚ └── file.go = brief description └── other/ = brief description Rules: - Explore the full directory structure before writing - One-line "= description" for every entry - Call out generated/never-edit files explicitly - Group related items but don't go deeper than 3-4 levels (summarize beyond that) - Include key files by name when they're important (e.g. router.go, api.ts) - Note ports, stack choices, and tools inline where relevant - Keep it scannable: someone should understand the project layout in 30 seconds ``` ### System architecture diagrams Claude once re-enabled nonce validation on this Go + Next.js blog without checking whether the frontend could actually send one. Production login broke. LLMs are great at reading code but get lost navigating 40 files, trying to figure out how it all connects. Get the agent to map it first. ```markdown Create docs/architecture.md with mermaid diagrams showing how this system works. Include the following diagrams where applicable β€” skip any that don't apply to this project: 1. System overview: all major components and how they connect 2. Request flow: how a user request travels through the system 3. Authentication flow: how auth works end-to-end 4. Deployment flow: how code gets from dev to production 5. Data flow: how data moves between services/stores Between each diagram, add 2-3 sentences explaining WHY things are wired that way, not just what the boxes are. Call out external services, cloud resources, and key infrastructure decisions. The primary audience is an AI coding agent that needs to understand the system architecture before making changes. Optimize for scannability. Keep it under 150 lines. ``` ### Cold Path: Domain Instruction Files prompt Load the rules every time, load the details only when needed. ```markdown Create domain-specific instruction files in .github/instructions/ for each major area of this codebase. Each file should: - Start with YAML frontmatter containing `applyTo` glob pattern matching the files it covers (e.g., applyTo: "apps/api/**/*.go") - Cover: project structure for that domain, conventions, patterns to follow, common gotchas, "never do this" warnings, and a complete code example - Be self-contained: an AI agent reading only this file should be able to work correctly in that area of the codebase - Include a "See Also" line pointing back to CLAUDE.md / AGENTS.md / GEMINI.md - Target 200-400 lines per file Create one file per distinct domain (e.g., backend language, frontend framework, database/SQL, tests, infrastructure/DevOps, HTTP handlers if they have unique patterns). Name them: {domain}.instructions.md Explore the codebase first to discover the actual conventions and patterns in use: don't invent new ones. Extract rules from what the code already does. ``` ### Hot Path: CLAUDE.md / AGENTS.md / GEMINI.md prompt Every line costs attention on every task. Make each one worth it. ```markdown Create a lean context file (~75 lines) that acts as a hot-path router. Use the appropriate filename for your AI tool: CLAUDE.md / AGENTS.md / GEMINI.md. This file is loaded into every AI conversation, so every line must earn its place. Structure it as: 1. Project identity (3-5 lines): stack, ports, one-sentence description 2. Essential commands (4-6 lines): only the commands needed every session (start dev, run checks, connect to DB) 3. Hard rules (8-12 lines): things that cause real breakage if violated. Only include rules where getting it wrong breaks the build, corrupts data, or causes production issues 4. Common workflows (8-12 lines): the 2-3 most frequent multi-step tasks as compressed numbered steps 5. Commit message format (3-5 lines) 6. Router table (~25 lines): three-column table mapping file paths to "read when..." triggers, grouped into domain guides, architecture & reference, and operations Rules for the router table: - Use task-language in "read when..." ("Writing Go code", not "Go conventions") - Every referenced file must actually exist - Group by: domain guides, architecture, operations Do NOT include in the context file: - Directory structure (belongs in docs/code-map.md) - Detailed command lists (belongs in domain .instructions files) - Full pattern explanations (belongs in .instructions files) - Authentication details (belongs in dedicated auth docs) - Troubleshooting tables (belongs in runbooks or .instructions files) Explore the codebase and existing docs first. Cross-reference with .github/instructions/ and docs/ to avoid duplication. ``` ### Go Antifragile with docs/footguns.md Troubleshooting is reactive ("something broke, now what?"), but footguns are preventive ("here's what will bite you before it does"). An AI reading footguns before making changes is higher leverage than an AI consulting troubleshooting after breaking something. ```markdown Read docs/footguns.md. If it doesn't exist, create it. Seed it with 2-3 footguns from this codebase - real cross-cutting issues you can find evidence of in the code, comments, or docs (not invented ones). Use this format per entry: ## Footgun: [short name] **Symptoms:** What the developer or AI sees when this bites **Why it happens:** Root cause spanning multiple domains **Prevention:** Concrete steps to avoid it Then add this line to the Hard Rules section of CLAUDE.md / AGENTS.md / GEMINI.md: - **Log footguns.** When you cause a bug that spans multiple domains (e.g., API + frontend, infra + auth), append it to `docs/footguns.md` using the existing format before closing the task. ``` --- **Bonus Tip** In GitHub copilot chat: ```markdown deeply review all the code changes in this PR AND review the github issue AND let me know if there's any blockers: ``` If this has been useful, feel free to star the repo and let me know what you built. Full templates and prompts: [github.com/blundergoat/ai-planning-playbook](https://github.com/blundergoat/ai-planning-playbook)

Plan Before You Prompt: Templates for AI-Assisted Development

21 February 2026 at 11:26
AI coding agents are fast, but they don't know what you know. Without upfront planning, a coding agent will scaffold an entire architecture around the wrong assumptions and you won't notice until you're 50 files deep. This is the 4-step framework I use before any coding agent touches my codebase: Feature Brief, Technical Requirements, Milestones, and Context Files. Full templates and prompts are in the [ai-planning-playbook repo](https://github.com/blundergoat/ai-planning-playbook). **Feature Brief.** Start with the initial requirements as you would without AI Assisted Development. This is the most important step and the one that most people skim over. The coding agent didn't attend that meeting last week, so it doesn't know what's most important until you let it know. **Technical Requirements.** AI coding agents can scan the codebase to help expand the initial plan into something more detailed. This section includes a Mob Elaboration prompt to help you lock in the exact requirements by generating structured, targeted questions. It also introduces Signal-based adaptive orchestration (SBAO) to refine the plan by leveraging multiple agents to review and critique each other. **Project Plan with Milestones.** Milestones make it easier to work on the right thing at the right time and help avoid context rot. Start with a proof of concept, then iterate toward something shippable. **Context files for AI Assisted Development.** Good prompts help. Context files win. This section covers how to build a lean hot-path router and cold-path domain files so your AI always knows what it needs - and doesn't waste attention on what it doesn't. ### How to use this playbook **Existing codebase with no context files?** Go straight to the Context files section. Copy the prompts into your coding agent and ask it to build a hot/cold file strategy for your project. **New feature or project?** Start with the Feature Brief. Create a `requirements-.md`, run it through the Mob Elaboration prompt, then use SBAO to pressure-test the plan with multiple agents before anyone writes code. **Ready to break work into tasks?** Use the Milestone Planning prompt to structure objectives, exit criteria, and gotchas before handing off to a developer or agent. Full templates and prompts at [github.com/blundergoat/ai-planning-playbook](https://github.com/blundergoat/ai-planning-playbook). ## Feature Brief **A Problem Well Defined is a Problem Half Solved** Start with what problem or pain point you are trying to solve. Creating good quality requirements is a skill that takes practice. The more detailed and specific you can be, the better. Requirements should cover not just what the feature does, but who it's for, what systems it touches, what the constraints are, and how we will know if it's successful. A brain dump is fine to start. It's most important that you understand why this feature request was made and how it benefits users. At the end of this process, you should have a clear and shared understanding that gives you the foundation for technical planning and building. The full `requirements-.md` template - covering Problem & Outcome, Users & Use Cases, Scope & Constraints, System & Impact, Risks & Assumptions, Success Criteria, and Delivery Plan - is available here [01-feature-brief-template.md](https://github.com/blundergoat/ai-planning-playbook/blob/main/01-feature-brief-template.md). ## Technical Requirements Now we have a clear feature brief, it's time to sharpen the plan. AI coding agents can scan the codebase and find gaps that might not surface until later. They can also ask clarifying questions early, before a developer picks it up. Two strategies help here. ### Mob Elaboration Prompt The AI does not guess what you want - it generates structured, targeted questions. The team answers those questions to lock in the exact requirements. ``` # ROLE You are an expert Technical Architect and AI Developer participating in a Mob Elaboration session. Your primary objective is to validate requirements and expose hidden complexities before any construction begins. Do not write any code. Do not guess, assume business logic, or hallucinate features outside the stated scope. # TASK I will provide a high-level intent or feature request. Your job is to interrogate this intent. You must generate a structured, highly targeted list of questions to lock in the exact requirements. # ELABORATION PROTOCOL Analyze my intent and ask exactly 3 to 5 clarifying questions, focusing on: 1. **Business Logic & Constraints:** What are the hard rules, data limitations, or specific performance requirements? 2. **Edge Cases & Failure Modes:** What happens when inputs are malformed, external services fail, or system limits are reached? 3. **Architecture & State:** How does this specific feature integrate with the existing system design? # INTERACTION & ARTIFACT RULES 1. **Halt and Wait:** After asking your questions, stop. Wait for my answers. We will iterate until I confirm the requirements are locked in. 2. **Synthesis:** Once I give the final approval, you will synthesize our discussion into structured artifacts. 3. **Context Separation:** You must separate the resulting plan into our established hot and cold files. Update the active, hot file (CLAUDE.md / AGENTS.md / GEMINI.md) with the immediate task breakdown, current state, and core execution rules. Any broader structural blueprints, such as generated Mermaid diagrams or system architecture maps, must be saved as separate, cold reference files. ``` ### Signal-based adaptive orchestration (SBAO) Ask multiple coding agents for competing plans. Have them rank and rate each other's plans out of 100 with reasons. - **Triangulation.** When two agents disagree, bring in a third to break the tie. - **Context sanitisation.** Ask AI in new chat, a litmus test for context rot. - **Adversarial cross-examination.** AI critiques each other, best idea wins. [SBAO](/articles/signal-based-adaptive-orchestration) the plan after writing the requirements yourself using multiple AI agents (e.g., separate chat sessions, Cursor multi-agent mode, different providers) and ask each one: ``` Deeply review the codebase and the following requirements (attach `requirements-.md`), and give me a technical plan in this file `TODO_feature-name_{model}.md` ``` Once the files have been created, ask the agents: ``` Rank each plan in a comparison table and rate them out of 100 with reasons. ``` Review their ideas and pick the best ones. Then ask your preferred agent to synthesize: ``` I've reviewed these competing plans. Here's what I like and don't like: **Keep:** [list the ideas, approaches, or architectural choices you want to keep] **Drop:** [list what you disagree with or want to change] **Decide:** [list open questions or trade-offs you want the agent to weigh in on] Create a best-of-all-ideas plan in `TODO_feature-name_prime.md` that incorporates the Keep items, avoids the Drop items, and makes a reasoned recommendation for each Decide item. ``` ## Project Plan with Milestones [LLMs Get Lost In Multi-Turn Conversation](http://arxiv.org/abs/2505.06120) is a research paper about models anchoring on early guesses in long conversations. That's where milestones help us avoid context rot with shorter sessions or explicit "re-read the requirements" checkpoints. So far we've started with a small plan, then sharpened and improved it. Now we need to structure that plan into actionable tasks. Each project is different, but the key is to start with a proof of concept that confirms the previous assumptions are correct and gives you something tangible to discuss. I've heard people say "do it right the first time", but we know more at 25% than we did on day one, and that usually changes the plan. 1. Prototype or proof of concept (prove it works) 2. Ready for internal testers (make it real) 3. Ready for live (make it solid) 4. Future improvements (make it shine) ### Milestone Planning Prompt The full milestone planning template with rules for spikes, assumption tracking, exit criteria, gotchas tables, and format guidelines, is here: [04-milestone-planning-prompt.md](https://github.com/blundergoat/ai-planning-playbook/blob/main/04-milestone-planning-prompt.md). ### The AI Trap: Fast BDUF AI makes Big Design Up Front dangerously easy. We can generate a fully future-proofed architecture in seconds, but the deeper we get, the more the context rots and the harder it is to change. By using the milestones above, we force the AI (and ourselves) into an Evolutionary model: | Feature | The AI BDUF Trap | Evolutionary / Iterative | |---|---|---| | **Primary Goal** | Perfect initial execution | Continuous learning and adaptation | | **Risk Profile** | High (back-loaded at launch) | Low (front-loaded in prototypes) | | **Cost of Change** | Exponentially expensive | Stays relatively flat | | **Documentation** | Heavy detailed, speculative | Living docs (like `CLAUDE.md`) | | **"Future Proofing"** | Attempted via over-engineering | Achieved via simplicity and decoupling | ## Context files for AI Assisted Development Persistent context files beat good prompts every time, but only if you separate your hot and cold paths. The size of your context files is a balancing act between the AI hallucinating (too small) and the AI suffocating (too big). Your CLAUDE.md (or AGENTS.md / GEMINI.md) should act as a lean router. Keep the hot path small to preserve the AI's attention budget for the actual task, while the cold path ensures it never lacks the deep knowledge required to execute properly. ### Generate Code Map prompt ``` Create docs/code-map.md: a quick-reference tree map of the repository layout. Use this format: project-name/ β”œβ”€β”€ file.yaml = brief description β”œβ”€β”€ dir/ β”‚ β”œβ”€β”€ subdir/ = brief description β”‚ └── file.go = brief description └── other/ = brief description Rules: - Explore the full directory structure before writing - One-line "= description" for every entry - Call out generated/never-edit files explicitly - Group related items but don't go deeper than 3-4 levels (summarize beyond that) - Include key files by name when they're important (e.g. router.go, api.ts) - Note ports, stack choices, and tools inline where relevant - Keep it scannable: someone should understand the project layout in 30 seconds ``` ### System architecture diagrams Claude once re-enabled nonce validation on this Go + Next.js blog without checking whether the frontend could actually send one. Production login broke. LLMs are great at reading code but get lost navigating 40 files, trying to figure out how it all connects. Get the agent to map it first. ``` Create docs/architecture.md with mermaid diagrams showing how this system works. Include the following diagrams where applicable β€” skip any that don't apply to this project: 1. System overview: all major components and how they connect 2. Request flow: how a user request travels through the system 3. Authentication flow: how auth works end-to-end 4. Deployment flow: how code gets from dev to production 5. Data flow: how data moves between services/stores Between each diagram, add 2-3 sentences explaining WHY things are wired that way, not just what the boxes are. Call out external services, cloud resources, and key infrastructure decisions. The primary audience is an AI coding agent that needs to understand the system architecture before making changes. Optimize for scannability. Keep it under 150 lines. ``` ### Cold Path: Domain Instruction Files prompt Load the rules every time, load the details only when needed. ``` Create domain-specific instruction files in .github/instructions/ for each major area of this codebase. Each file should: - Start with YAML frontmatter containing `applyTo` glob pattern matching the files it covers (e.g., applyTo: "apps/api/**/*.go") - Cover: project structure for that domain, conventions, patterns to follow, common gotchas, "never do this" warnings, and a complete code example - Be self-contained: an AI agent reading only this file should be able to work correctly in that area of the codebase - Include a "See Also" line pointing back to CLAUDE.md / AGENTS.md / GEMINI.md - Target 200-400 lines per file Create one file per distinct domain (e.g., backend language, frontend framework, database/SQL, tests, infrastructure/DevOps, HTTP handlers if they have unique patterns). Name them: {domain}.instructions.md Explore the codebase first to discover the actual conventions and patterns in use: don't invent new ones. Extract rules from what the code already does. ``` ### Hot Path: CLAUDE.md / AGENTS.md / GEMINI.md prompt Every line costs attention on every task. Make each one worth it. ``` Create a lean context file (~75 lines) that acts as a hot-path router. Use the appropriate filename for your AI tool: CLAUDE.md / AGENTS.md / GEMINI.md. This file is loaded into every AI conversation, so every line must earn its place. Structure it as: 1. Project identity (3-5 lines): stack, ports, one-sentence description 2. Essential commands (4-6 lines): only the commands needed every session (start dev, run checks, connect to DB) 3. Hard rules (8-12 lines): things that cause real breakage if violated. Only include rules where getting it wrong breaks the build, corrupts data, or causes production issues 4. Common workflows (8-12 lines): the 2-3 most frequent multi-step tasks as compressed numbered steps 5. Commit message format (3-5 lines) 6. Router table (~25 lines): three-column table mapping file paths to "read when..." triggers, grouped into domain guides, architecture & reference, and operations Rules for the router table: - Use task-language in "read when..." ("Writing Go code", not "Go conventions") - Every referenced file must actually exist - Group by: domain guides, architecture, operations Do NOT include in the context file: - Directory structure (belongs in docs/code-map.md) - Detailed command lists (belongs in domain .instructions files) - Full pattern explanations (belongs in .instructions files) - Authentication details (belongs in dedicated auth docs) - Troubleshooting tables (belongs in runbooks or .instructions files) Explore the codebase and existing docs first. Cross-reference with .github/instructions/ and docs/ to avoid duplication. ``` ### Go Antifragile with docs/footguns.md Troubleshooting is reactive ("something broke, now what?"), but footguns are preventive ("here's what will bite you before it does"). An AI reading footguns before making changes is higher leverage than an AI consulting troubleshooting after breaking something. ``` Read docs/footguns.md. If it doesn't exist, create it. Seed it with 2-3 footguns from this codebase - real cross-cutting issues you can find evidence of in the code, comments, or docs (not invented ones). Use this format per entry: ## Footgun: [short name] **Symptoms:** What the developer or AI sees when this bites **Why it happens:** Root cause spanning multiple domains **Prevention:** Concrete steps to avoid it Then add this line to the Hard Rules section of CLAUDE.md / AGENTS.md / GEMINI.md: - **Log footguns.** When you cause a bug that spans multiple domains (e.g., API + frontend, infra + auth), append it to `docs/footguns.md` using the existing format before closing the task. ``` --- If this has been useful, feel free to star the repo and let me know what you built. Full templates and prompts: [github.com/blundergoat/ai-planning-playbook](https://github.com/blundergoat/ai-planning-playbook)
❌
❌