Enjoy Newsletter #48.

TODOs aren’t for doing

Sophie Alpert pushes back against two common policies for handling TODO comments in codebases: requiring every TODO to have a corresponding ticket in an issue tracker, or automatically deleting TODOs that have sat around too long. In her view, only urgent TODOs like “Finish writing the second half of this file so next week’s launch doesn’t crash” actually need to be tracked as tasks. The most valuable TODOs aren’t meant to be done at all: they document edge cases and design hints, such as “if the user clicks this button three times in a row, the event handler will break”—a rare scenario the author noticed but didn’t need to fix yet.

The real value of these comments is preserving the original author’s train of thought and context. When another developer reads the code later and wonders whether a structure could be written differently, a well-placed TODO answers that question immediately, giving them the confidence to refactor instead of hesitating out of fear that the original author knew something they didn’t. For junior developers, this is a helpful perspective: treat TODOs as small notes left for future readers rather than a backlog of chores that must be swept clean.

Automating Away Claude’s Bad Habits with Hooks

Claude Code frequently leaves trailing whitespace at the end of lines because language models generate text token by token without “seeing” the rendered formatting, and telling it not to in instructions is unreliable. Brian Cosgrove solves this cleanly using hooks—user-defined shell commands that run automatically at specific points in Claude’s workflow loop. Specifically, he configures a PostToolUse hook that runs RuboCop with the Layout/TrailingWhitespace rule every time Claude edits a Ruby file. He deliberately chooses a language-aware linter over a generic sed or regex replacement, which could corrupt binary files or break trailing-space line breaks in Markdown and other whitespace-sensitive formats.

Beyond PostToolUse, hooks also support PreToolUse, Notification, Stop, and SubagentStop events, allowing you to inspect, transform, or block actions at various stages: running linters, executing tests, verifying that code compiles, or preventing risky operations like committing untested code. The author also warns that hooks run with the user’s full permissions, so you should read every command carefully before adding it, as a malicious hook could compromise your system during routine Claude operations. This is a practical example of turning AI’s “bad habits” into automatically corrected steps rather than repeating yourself in prompts.

Docs for AI Agents

Kayce Basques shares thoughts on documentation written for AI agents and how it relates to internal technical documentation that engineering teams write for themselves, such as RFCs or build guides. Agent docs make agent outputs more consistent, aligned with project conventions, and accurate: when first using Claude Code, the author noticed the tool correctly guessed the site used Sphinx built with Bazel, but ran the wrong command; adding the right command to the agent doc fixed it permanently. Each tool looks for its own root file (CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI, AGENTS.md for Codex CLI), and the file’s contents are injected verbatim into the system prompt on every model call, so it needs to stay concise. Subdirectory and user-level agent docs are also supported.

The big question is whether to maintain two separate sets of documentation. Reasons to keep them separate include different writing styles, agents’ need for brevity versus humans’ need for comprehensive context, and the fact that models already know many general concepts; the reason to merge them is avoiding duplication and drift over time. The author suggests several approaches: using AI itself to keep the two sets in sync, merging them into one, embedding agent instructions as comments inside human docs and extracting them via a script, using @ imports to pull in files like CONTRIBUTING.md, or using pre-merge checks to enforce that related files are updated together.

Developers Are Using These AI Agents to Build Software 10x Faster

This article rounds up AI coding agents that are helping developers move significantly faster in 2025, with brief descriptions of how each tool automates parts of the workflow. The list includes Cursor (an AI-first editor with real-time suggestions), Emergent (multi-agent orchestration for generating features and preparing deployments), DeepDocs (automatically syncing GitHub documentation with code changes via GitHub Actions), Continue.dev (an open-source platform for building custom AI-integrated IDEs), ByteDance’s Trae (end-to-end web app development with multimodal input support), Cline (a VS Code extension built for large codebases), Google’s Gemini CLI and Sourcegraph’s Cody CLI (in-terminal assistants), OpenHands (an autonomous open-source agent framework), Replit AI (a cloud environment with built-in database support), Augment Code (an IDE-integrated agent that can run code and spot performance issues), and CodeRabbit (automated GitHub pull request reviews).

The central message is that these agents take over repetitive tasks, enabling faster delivery and cleaner code for solo developers, startups, and large enterprises alike. The author concludes that adopting a few such tools in your 2025 workflow is shifting from a productivity boost to a necessity. For newer developers, it serves as a handy survey for picking tools to try out.

What kind of work I want (in 2025)

Sean Goedecke candidly lists the kind of engineering work he wants in 2025—a great template for any engineer thinking deliberately about their career path. On work environment, he prioritizes fully remote roles with occasional in-person gatherings over mandatory hybrid policies; he prefers low-process management that trusts engineers without heavy scrum ceremonies, and wants to stay based in Australia. On projects, he looks for work at the core of the business that leadership cares about, including unglamorous systems like billing; he excels at getting things done inside large monolithic codebases and prefers iteratively improving an imperfect solution over polishing indefinitely.

He targets large US tech companies or comparable Australian firms, avoids startups, wants to work on large-scale systems people have heard of, and is currently very interested in AI both as a tool and as a transformative technology. His ethical boundaries are explicit: no proof-of-work blockchain, online gambling, autonomous weapons, or predatory financial services, alongside a strong preference for diverse teams. The biggest shift since 2021 is abandoning the idea of building a safe career maintaining legacy systems—since those roles are prime targets during layoffs—in favor of high-priority initiatives; his expectations of managers have also simplified down to competence and honesty.

Welcoming The Next Generation of Programmers

Armin Ronacher, creator of Flask, argues that AI coding tools will expand rather than shrink the programming profession: AI will not reduce the number of programmers—in fact, the opposite seems much more likely. His definition is deliberately inclusive: “If you create a program, whether by hand or with the help of an agent, you are a programmer.” He sees growing consensus that newcomers will and should write AI-generated code, and points to the Python community’s tradition of openness—through initiatives like PyLadies—as a model for welcoming this new wave of learners.

The challenge he highlights is that whereas new programmers used to learn alongside human mentors, those learning through ChatGPT may lack human connection altogether. Rather than looking down on “vibe coders,” the community should actively mentor them and build pathways into the broader ecosystem, so tooling companies don’t turn them into dependent users with no incentive to learn deeper fundamentals. The goal is to turn isolated human-AI interactions into a shared learning journey that helps the next generation develop sound software engineering practices.

Pattern-matching across different languages

Nicolas Fränkel compares how pattern matching is supported across Java, Scala, Kotlin, Python, and Rust, starting from the traditional C-style switch statement. Every example uses the same geometric hierarchy of Rectangle and Circle with a perimeter function, combining type matching and pattern guards to detect when a rectangle is a square. Java 23 uses switch expressions with arrow syntax, supporting type patterns and when guards, selecting the first matching branch. Kotlin uses when expressions and is checks, with the article’s example enabling an experimental flag for guards. Python added the match statement in 3.10, which destructures attributes by name very cleanly. The Rust translation uses trait objects and downcasting, making it more verbose; the author explicitly notes that this setup is not idiomatic and does not reflect Rust’s true pattern-matching strengths.

Among the languages compared, Scala pioneered pattern matching early on and still stands out for destructuring and extracting class fields directly inside a match arm without extra variable bindings; it inspired the other languages, though the author notes Java and Kotlin have largely closed the gap in this example. He concludes that pattern matching combined with destructuring makes code significantly more readable and maintainable—a technique well worth learning in any modern language.

A real-world AI coding case sample

Korny shares a real-world walkthrough of using Claude to add a feature to an ASP.NET Core application: publishing a PersonBusinessLink event to Kafka with a “linked” or “unlinked” type whenever a contact person is associated with or removed from a business. The project uses monadic Result and Option return types, domain-driven design with repositories and services, and Kafka running in Docker with Testcontainers for integration tests. Rather than letting Claude run on autopilot, he guided it step by step: first asking it to identify existing patterns in the codebase, then requesting the feature with a detailed spec, reviewing every change before committing, and stepping in when Claude picked the wrong Kafka topic or partition key. When Claude struggled with the monadic control flow, he debugged it himself rather than letting it spin its wheels.

Claude did well at learning test conventions from existing files and handling straightforward boilerplate, but needed course correction on architectural decisions and couldn’t resolve deeper bugs on its own. The author’s advice is to treat AI like a very fast, enthusiastic, but naive junior developer: useful when carefully guided, but not reliably autonomous on complex tasks. He also raises serious concerns about the environmental cost, unsustainable venture funding, and the motives of the companies behind these tools.

Clowns to the Left of Me…

Korny reflects on the polarized debate around AI coding tools and places himself squarely in the middle, echoing the song “Stuck in the Middle With You” referenced in the title. On one side are the hype evangelists claiming 50x productivity gains, advocating coding without regard for security, and getting swept up in the thrill of rapid code generation—leading them to overstate capabilities and downplay risks. On the other side are the skeptics, who are right to push back against exaggerated claims, but sometimes treat preliminary studies as definitive proof and dismiss the tools after a few low-context tries.

The author takes a pragmatic view: the tools genuinely help him in real work—such as writing Python scripts, generating diagrams for documentation, or spotting security vulnerabilities—but require careful prompting, output verification, and choosing the right use cases. What matters is learning when and how to use them effectively; he recommends following balanced practitioners like Simon Willison and Birgitta Böckeler. Still, he stresses that we shouldn’t ignore systemic issues: massive energy consumption, environmental harm tied to fossil fuels, unsustainable VC subsidies, and power concentrated in the hands of controversial tech leaders. Bottom line: evaluate the tools through evidence and hands-on experience.

Improving the prompt to the AI to get better code

The author of Vanilla Java Blog experiments with optimizing a Java method that formats a time zone offset from milliseconds into ISO 8601 (±hh, ±hhmm, or ±hhmmss) while allocating as few objects as possible for low-latency applications. Initial “one-shot” prompts produced wildly uneven results across models. A refined prompt spelled out explicit constraints: use a ThreadLocal buffer, stick to simple arithmetic, avoid String.format and object allocations, and return an intern()ed string. This guidance helped weaker models improve dramatically.

Seven systems were evaluated: Gemini 2.5 Pro, o3-pro, o4-mini-high, Claude 4, Grok 3 Think, GitHub Copilot with GPT-4.1, and Microsoft Copilot in Think Deeper mode. Response times ranged from a few seconds to 18 minutes without a corresponding jump in quality. Most solutions used a ThreadLocal char[] buffer and manipulated digits directly, but not a single model suggested using byte[], even though modern Java strings store characters internally as a byte array. The takeaways: detailed prompts narrow the gap between models, longer thinking time does not guarantee better code, and AI can still miss specialized performance tricks; the best approach is testing multiple models and iterating on the prompt rather than asking just once.


This post was rewritten by Claude Code with Opus 5.5 on 27/09/2026; reviewed and edited by Codex with GPT 6.1 Sol on 09/11/2026, and re-verified by Claude Code with Sonnet 5.5 on 16/11/2026.