Most “agent” use cases are actually workflows, a known sequence of steps where one or two of those steps happen to involve an LLM. You don’t need autonomy for that. You need a function call.
He points out that functions compose predictably, so if you know the workflow, then composing in a program text is better than agents figuring out how to coordinate themselves. It’s faster, and needs less tokens. It’s usually easier to deal with failures, since the scope of the interaction is smaller.
Pritchard also thinks that people use skills far more than they should. He thinks people accumulate folders of markdown skill files but LLMs use them inconsistently, often missing them when they’re needed, or bloating context when they are not. Many things that should go in skills should be other parts of a harness, preferably computational. Skills should only be used with deliberate, infrequent workflows.
The skills obsession is a symptom of a deeper pattern: people reaching for configuration when they should be reaching for architecture.
Consider that ArchUnit can let you build tests like the following:
@AnalyzeClasses(packages="com.example")
public class SinglePublicMethodRuleTest {
@ArchTest
static final var usecases_should_have_only_one_public_method =
classes()
.that()
.resideInAPackage("..usecases..")
.should(haveOnlyOnePublicMethod())
}
The actual rules should of course be specific to your project and modular to the modules within. This kind of stuff often gets leaked to skills files when it can be done perfectly well with deterministic tools.
Keeping code maintainable largely means keeping it comprehensible. Comprehensibility comes with architecture that enforces relationships across “entities” that are easier to reason about. When the entities are code, the architecture includes abstractions, adherence to using terminology from the domain of the system, and style heuristics.
Style heuristics include things like immutability, method lengths, line lengths against nesting, condition lengths before they’re refactored into explainer variables, all that makes cyclomatic complexity balloon up. With good style heuristics, you require less cognitive load to build abstractions, and you build better abstractions as a result. With poor style heuristics, your abstractions need to abstract such large surface areas that namespaces tend to collapse, and code reviews become a headache.
When I started agent-assisted coding, I struggled between setting the agent instructions, and wanting it to do things my way in a manner that “skills” was too unreliable for. Your “feedback loop” is not just the sum of tools you have fitted into your agentic workflow, you can also further categorize your prompts broadly into domain-feature/bug resolution/migration instructions (the meat of the chore), and refactoring instructions like how functionality is grouped, how you want variables to be named, etc.
When these style heuristics were violated during my earlier exploration with Claude Code, I thrashed with finding the balance between using the agent for feature work vs refactoring work. Refactoring work felt like it was bogging down the feedback loop, it was pedantic and it felt non-idiomatic.
It felt non-idiomatic because agents should essentially be seen as injections of non-determinism in our systems. Trying to reimagine those computing systems as inherently non-deterministic now because of AI and the need for reinvention is not just terribly misguided, but it also reflects the lack of an engineering intuition and bone in one’s perspective.
When we know agents are making our code quality worse, as engineers, our job is break problems down into smaller problems and solve them, not wish for Anthropic to fix it in the next Opus model.
Code style heuristics are like a developer’s handwriting, or an organization’s culture. They cannot be passed by a singular organization like Anthropic anyway. Abandoning them is not just not necessary, but these heuristics are in fact shortcuts that save extra work from being done. That “non-determinism” (AI generated code) does not need to be corrected in the form of a human feedback loop and those decisions can be automatically enforced by some tests and rules on code “styles” instead, instead of just the code’s behavior and execution path.
If these heuristics can be encoded as deterministic tests and rules using ArchUnit and SonarQube, it frees us up into breaking down “coding” itself as a problem and solve those individually with AI. I categorize code, or work that I do in writing features, as dealing with:
For architecture, one can study books, learn from good codebases, study different styles like functional programming, and gain practice and experience at their job for improvement. For better abstractions, one must understand the business domain better. For naming skills, it is simply your skills in the English language, and for performance and security, it is what we learn in academia with respect to algorithms and maths.
In agent assisted coding the same things map to the use of artifacts and tools. The interesting part is not skills, but how well you can inject the context and make use of deterministic tooling to restrain the agent from making mistakes. And it remains work that requires human interaction, comprehension and decision making, that LLMs fundamentally cannot do, and which is what keeps these tasks interesting and within the realm of “engineering”.
For architecture, explore ArchUnit. For the business domain, inter-departmental interaction requires human communication for identification and resolution of misunderstandings and scopes of work. The artifact is documentation. How is this going to be injected? Naming is done well enough automatically by the LLM if the architecture is good enough to keep namespaces well spaced. Maybe add some rules about explainer variables and condition complexity in conditional clauses using ArchUnit and SonarQube. For performance and security, again SonarQube can be used, but also other SaaS tools that are in use today by large organizations.
Again, that all these things are yet to become commonplace makes me still feel relevant as a software engineer.
]]>The core idea is learning to code in a style that makes the boundaries of change clear, such that when changes are made, typically by an AI agent, you can be confident that unexpected “side-effects” will not occur as a result. This entails using practices like guard clauses and immutability which come from functional programming.
Over time it will help evolve in you a sense of seeing code as states and outcomes, a level of abstraction higher than seeing code “imperatively”, i.e. in loops and conditions. Working at a higher abstraction level = more comprehension with less effort, which is something that also goes far with LLMs.
The benefit is twofold: not only do code reviews become faster, but the codebase is left in a more maintainable state. Changes become easier to reason about, reducing both the cognitive load on human reviewers and token use with AI agents.
These examples depict real world usecases of existing code + a delta of change representing challenges with maintainability of code. By the way, “memory” features like Claude.md make inculcating these patterns trivial, it is your human brain you must train to see the patterns in this style of coding.
Consider the following example, which I have frequently seen in codebases, of nested statements.
public boolean assemblyCheck() {
boolean result = true;
if (pants.arePressed()) {
if (belt.isBuckled()) {
if (collar.isFixed()) {
if (buttons.areFastened()) {
if (jacket.isBrushed()) {
if (cuffs.areAdjusted()) {
if (tie.isStraightened()) {
result = true;
} else {
teacher.straighten(tie);
result = false;
}
} else {
result = false;
}
} else {
student.remove(jacket);
result = false;
}
} else {
result = false;
}
} else {
teacher.fix(collar);
result = false;
}
} else {
result = false;
}
} else {
result = false;
}
return result;
}
Suppose an agent made a change as the BasketService is now meant to be used. Can you spot the error?
public boolean assemblyCheck() {
boolean result = true;
if (pants.arePressed()) {
if (belt.isBuckled()) {
if (jacket.isBrushed()) {
if (collar.isFixed()) {
if (buttons.areFastened()) {
if (cuffs.areAdjusted()) {
if (tie.isStraightened()) {
result = true;
} else {
teacher.straighten(tie);
result = false;
}
} else {
result = false;
}
} else {
result = false;
}
} else {
student.remove(jacket);
Jacket substituteJacket = basketService.fetchSubstitute();
student.wear(substituteJacket);
result = false;
}
} else {
result = false;
}
} else {
result = false;
}
} else {
result = false;
}
return result;
}
Consider below the functionally equivalent case with guard clauses.
public boolean assemblyCheck() {
if (!shirt.isIroned()) return false;
if (!shoelaces.areTied()) return false;
if (!shoes.arePolished()) return false;
if (!pants.arePressed()) return false;
if (!belt.isBuckled()) return false;
if (!collar.isFixed()) return false;
if (!buttons.areFastened()) {
student.remove(jacket);
Jacket substituteJacket = basketService.fetchSubstitute();
student.wear(substituteJacket);
return false;
}
if (!jacket.isBrushed()) return false;
if (!cuffs.areAdjusted()) return false;
if (!tie.isStraightened()) {
teacher.straighten(tie);
return false;
}
return true;
}
Can you spot the error now? (The nested and early return code snippets are functionally equivalent.)
As computer scientists, our ability to break problems into sub problems before solving them is core to a systems approach. Similarly, in inductive reasoning in maths, we identify and get rid of simpler cases first to make our lives easier.
The error is that the basketService code is tied to the collar.isFixed() condition instead of the jacket.isBrushed() condition where it should be. Nesting clauses fling “else” clauses far down the line, making it non trivial to decipher which code is logically coupled to which case.
Where would you add the new condition, pants.areTheRightSize()?
In nested code, introducing another level of nesting at the deepest level can feel intuitive, before any else statements require you to shuffle around brackets. Switching up the order of if-cases is jarring with moving braces and logic to be deciphered to ensure correctness is maintained.
With the early-return style, reordering conditions in most IDEs is a simple select then Alt+Up or Alt+Down, versus nested code where braces have to be carefully aligned.
Consider how much easier it is to add a new condition to the early-return style code. It is much easier to notice in this style also that there is already a condition coupled with pants in the method (if(!pants.arePressed())) in this style, and factor it out into a separate method.
For example, here’s the refactored version with pants checks extracted:
public boolean assemblyCheck() {
if (!shirt.isIroned()) return false;
if (!shoelaces.areTied()) return false;
if (!shoes.arePolished()) return false;
if (!checkPants()) return false;
if (!belt.isBuckled()) return false;
if (!collar.isFixed()) return false;
if (!buttons.areFastened()) {
student.remove(jacket);
Jacket substituteJacket = basketService.fetchSubstitute();
student.wear(substituteJacket);
return false;
}
if (!jacket.isBrushed()) return false;
if (!cuffs.areAdjusted()) return false;
if (!tie.isStraightened()) {
teacher.straighten(tie);
return false;
}
return true;
}
private boolean checkPants() {
return pants.arePressed() && pants.areTheRightSize();
}
It is no surprise that in codebases where nesting is preferred, scopes are not regularly extracted and methods tend to run very long.
This harms readability: In 1 huge method, the search space for changes is much larger, compared to the same method split into 5, where you might safely be able to ignore scopes that haven’t been touched by changes.
Refactoring into smaller methods has an often overlooked benefit: better naming. In long methods with large scopes, the namespace shrinks, leading to variable names with 3-4 prefixes that ultimately don’t make immediate sense either. In smaller methods, you can use simpler names because the method name itself is part of your mental context window.
Consider this typical long method:
public void processUserOrder() {
// ... 50 lines of code ...
boolean userOrderPaymentVerified = paymentService.verify(order);
String userOrderPaymentTransactionId = payment.getTransactionId();
boolean userOrderInventoryAvailable = inventory.check(order.items);
String userOrderInventoryReservationId = inventory.reserve(order.items);
boolean userOrderShippingAddressValid = validateAddress(user.shippingAddress);
String userOrderShippingTrackingNumber = shipping.createLabel(order);
if (userOrderPaymentVerified && userOrderInventoryAvailable && userOrderShippingAddressValid) {
// ... more code with these long names ...
}
}
Every variable needs a prefix (userOrder + Payment + Verified) because in a large scope with many concerns, you need to disambiguate. The method handles payment, inventory, and shipping all at once, so variable names become bloated.
Now contrast with smaller, focused methods:
public void processUserOrder() {
if (!verifyPayment(order)) return;
if (!reserveInventory(order)) return;
if (!scheduleShipping(order)) return;
completeOrder(order);
}
private boolean verifyPayment(Order order) {
boolean isVerified = paymentService.verify(order);
String transactionId = payment.getTransactionId();
if (isVerified) {
order.setTransactionId(transactionId);
return true;
}
return false;
}
private boolean reserveInventory(Order order) {
boolean isAvailable = inventory.check(order.items);
String reservationId = inventory.reserve(order.items);
if (isAvailable) {
order.setReservationId(reservationId);
return true;
}
return false;
}
private boolean scheduleShipping(Order order) {
boolean isAddressValid = validateAddress(user.shippingAddress);
String trackingNumber = shipping.createLabel(order);
if (isAddressValid) {
order.setTrackingNumber(trackingNumber);
return true;
}
return false;
}
In small methods, the method name can be relied upon to already be in your mental context window, so you don’t need to repeat yourself. The freer namespace enables you to assign more specific, relevant and less ambiguous names.
Consider the following shopping basket implementation:
public class ShoppingBasket {
private List<LineItem> items;
private double totalCost;
public void addItem(String productId, int quantity, double unitPrice) {
LineItem item = new LineItem(productId, quantity, unitPrice);
items.add(item);
totalCost += unitPrice * quantity;
}
public void removeItem(String productId) {
LineItem item = findItem(productId);
if (item != null) {
items.remove(item);
totalCost -= item.getUnitPrice() * item.getQuantity();
}
}
public void updateQuantity(String productId, int newQuantity) {
LineItem item = findItem(productId);
if (item != null) {
int oldQuantity = item.getQuantity();
item.setQuantity(newQuantity);
totalCost += item.getUnitPrice() * (newQuantity - oldQuantity);
}
}
public double getTotalCost() {
return totalCost;
}
}
totalCost is a property of the class. Each method is like an event that updates its value. Can you spot the bug here?
Mutable state is typically obscuring two realities about your code:
totalCost += whatever) represents a scattered logic. This logic can be extracted from across those methods and unified into one, new, communicatively named method (such as calculateTotalCost() in our case). Doing this leaves methods lighter and more maintainable.Your job then must be to realize that there is a scope one level above this current scope that is both (1) using your methods, and (2) relying on the state they are mutating. Here is where you should process the mutating state.
Realize the object value in this scope, only when needed, in the proximity of where it is actually being used to make it easier to understand how its being used, and name it specific to this context, not reusing names from a scope below that breaks the mental model of encapsulation.
// ViewModel uses calculateTotalCost() and names it for UI context
public class BasketView {
public double projectedBillWidget(ShoppingBasket basket) {
...
// the "total" in method name is specific to the
// shopping basket scope, its a total over the
// line items. variable name "lineItemsCost" is
// specific to this context. this is better
// encapsulation. in the view, "total"
// may otherwise be confused with the basket
// total, post discount total, maybe the payment
// is split with a redeemed voucher and loyalty
// points. a new variable automatically forces you
// to be more specific about naming
final lineItemsCost = basket.calculateTotalCost();
final discounts = ...
final costCharged = basketCost - discounts;
return Column(
"lineItemsCost": "$" + lineItemsCost.with2Decimals,
"discounts": "- $" + discount.with2Decimals,
"=========="
"costCharged": "$" + costCharged.with2Decimals,
);
}
}
// Service uses it and names it for business context
public class OrderService {
public OrderResponse processOrder(ShoppingBasket basket) {
double chargedAmount = basket.calculateTotalCost() + x + y + z;
// ... process payment ...
return new OrderResponse(chargedAmount);
}
}
public class OrderResponse {
private final double chargedTotalCost;
public OrderResponse(double chargedTotalCost) {
this.chargedTotalCost = chargedTotalCost;
}
}
Those who resist this approach often cite the memory cost of immutability over mutable state. But in most cases, defaulting to mutability for memory reasons is premature optimization. The garbage collection of immutable variables in small methods is trivial. If there actually is a memory constraint, profiling should be done and cache mechanisms could be considered, mutability being seen as one such cache mechanism.
Additionally, this is easier to maintain. Tomorrow if you realize you want to change totalCost based on time specific discounts for Christmas or Labor Day or so, you can do that swapping the calculated value with an output from a service that can be swapped at runtime. Just one maintenance scenario that would have been trickier to otherwise accomplish with deeply rooted mutating state.
The definition for functions was taught to me in grade school, a function is something that, for a given input, always maps it to the same output.
The input for a function is its arguments. You only need to understand the arguments passed and the method body to be able to make changes to it.
public static double calculateDiscount(double price, double rate) {
return price * rate;
}
The input for methods is their arguments + the properties the object its called on has access to. To make changes to a method, you need to understand the arguments, the method body, and additionally these object properties.
public class PricingCalculator {
private final double discountRate;
public PricingCalculator(double discountRate) {
this.discountRate = discountRate;
}
public double calculateDiscount(double price) {
return price * discountRate;
}
}
// Usage
PricingCalculator calculator = new PricingCalculator(0.1);
double discount = calculator.calculateDiscount(100.0);
If these object properties were immutable/final, you only need to look at one place, i.e. where the object was initialized, to understand how their value may vary. When these properties are mutable however, you have to understand every place where this property is mutated.
public class ShoppingCart {
private double discountRate; // ← mutable state
public ShoppingCart() {
this.discountRate = 0.0; // mutation #1
}
public void applyMemberDiscount() {
this.discountRate = 0.1; // mutation #2
}
public void applySeasonalDiscount() {
this.discountRate = 0.15; // mutation #3
}
public void applyLoyaltyBonus() {
this.discountRate += 0.05; // mutation #4
}
public double calculateDiscount(double price) {
return price * discountRate; // depends on mutations #1-4
}
}
// Usage
ShoppingCart cart = new ShoppingCart();
cart.applyMemberDiscount();
cart.applyLoyaltyBonus();
double discount = cart.calculateDiscount(100.0); // What is discountRate now?
Every place where this value is mutated gives rise to n more states that your function now has to cater to. Not catering to these states risks leaving your application in an invalid state. It may be fine today but in a year’s time doing this will leave your system riddled with bugs regarding “unexpected” use cases.
It is often even much much worse than this example, because when folks are not careful about mutation, in reality they will be mutating state far beyond the scope of one class into other classes which mutate other classes, and building a mental model of this will be complex in a way that you could mathematically even then demonstrate.
The more immutable properties being used by your methods, the more “impure” your function is, impurity here referring to how dependent your output is on mutable, external variables. For a human or an AI agent, this makes it difficult to reason about, as the search space for changes explodes exponentially, and making changes to such classes becomes slow and risky.
Using the term “function purity” has a tendency to upset software engineers however, and you will find accusations of rigidity and impracticality common in such discussions at the mere mention of this word.
What is important to remember is that purity is a spectrum that you can slide both high and low on. Don’t uproot your whole codebase to start implementing this advice. You don’t have to be 100% pure 100% of the time. But you do need to understand what it means so you can use it as a warning sign of your code quality.
These guidelines aren’t absolute. There are times when mutable state is the right choice: performance-critical loops, large data structures where copying is prohibitively expensive, stateful systems like game engines or UI frameworks where state machines are idiomatic.
But here’s the key: you yourself will be a bad judge of the exceptions. The things that are obvious and simple to you as the author of the code will not be similarly obvious to another maintainer or yourself in a week’s time.
These styles require learning to see code in a certain way. They don’t ask you to refactor a whole codebase today. They’re defaults, not additional structures, that keep you in flow state for longer by shrinking the search space for code reviews. Hopefully they will make coding more joyful and less adversarial with AI agents when you have to deal with the 23423th suggested code review of the day.
Comments welcome here; https://www.linkedin.com/posts/sohaibbaig1_shrinking-the-search-space-for-code-reviews-activity-7456003268729692161-cDW6
]]>