I don’t know that I’ll ever stop wanting to review agent code. I understand that probably makes me much slower compared to people who accept it as-is and ship to prod, but at the very least it seems like I’m not the only one¹.

My rationale is twofold:

1. I echo the sentiments of those who talk about losing touch with code and its architecture. Despite my efforts to combat that, I still find myself asking “how did that thing work again?” Maybe it’s because I’m now covering a lot more breadth over a shorter period of time. Maybe I’m getting older. Maybe it’s both. I don’t remember finding myself in this position as often as I do now.
2. If I’m going to be on the hook for the code I ship, then I want to know what’s in it and I want to build it with posterity in mind. I’ve spent quite a lot of time learning what actually works in production: why would I throw that all away? If I can use that experience to shape outcomes, why wouldn’t I?

When I review agent code, I look for architecture or implementation problems. Architecture problems commonly arise from non-exhaustive planning where there was some gap in my understanding of the problem space that wasn’t filled by either my own research or the agent’s. Implementation problems commonly arise out of wrong architecture choices: solutions that don’t fit the framework, the language or even the structure of the existing codebase. These problems are not unique to agents.

Agents have introduced a new kind of implementation problem, one that arises out of the agent’s inherent stochasticity. Even when you get the architecture right, its taste in code structure and modularity is more informed by which branch of the decoding loop it took than some objective measure.

All of these scenarios produce code that you would expect a concientious engineer to cleanup. Agents are not concientious which is why we oftentimes find ourselves reviewing slop.

Partway through one of my review sessions, I asked myself a simple question: can the intuition I have about what makes code “clean” be automated? If it can be automated, can an agent use it?²

Static analysis has been in the engineering toolbelt for a very long time³ and tools⁴ that analyze programs are abundantly available and regularly used. One class of static analysis I haven’t seen used broadly⁵ is the kind of tool that tells you your code has too many conditionals, or that your functions are too big, or that you have an object with methods that don’t share any state. Essentially, the kind of tool that tells you how sloppy your code is.

I attribute this to two things:

1. Building consensus is hard⁶. Even more so when it’s about something subjective like taste.
2. There has, till recently, not been a generic tool that can automatically transform a body of code in a way that minimizes this kind of objective.

I⁷ wrote mdlr to give agents that objective, because

1. I now have half the time to review 2-3x the code
2. I need to be able to jump into any part of the diff or codebase and quickly get up to speed
3. I want one tool that I can use across multiple programming languages
4. Cleaning up dirty code is not my preferred method for staying sharp⁸

mdlr scans a codebase and outputs a list of metrics and their associated symbols sorted in descending severity. Here’s an example output.

$ mdlr check --pretty
metric         symbol                       value  bucket
function_size  replay_endpoint_error::main  141    critical
cognitive      replay_endpoint_error::main  26     critical
cyclomatic     replay_endpoint_error::main  18     critical

Getting an agent to use this is very simple: ask it to run mdlr prompt and follow the instructions.

$ mdlr prompt

# Auto-Improve

Use mdlr to identify and improve modularity issues in the codebase.

## mdlr Reference

### Quick Start

# Analyze codebase (diff mode on branches, all files on main/master)
mdlr check

# Force all files even when on a branch
mdlr check -A

# Analyze specific directory or file
mdlr check src/metrics
mdlr check src/main.rs
...

Here’s an example that Claude was able to improve entirely on its own with this tool. This is part of a script I had it build to help me debug query timeouts in ClickHouse.

def main():
    # ...argparse setup for --set, --delete, --gap, --explain, --output...
    args = parser.parse_args()

    if not args.file.exists():
        print(f"Error: {args.file} not found", file=sys.stderr)
        sys.exit(1)

    error = json.loads(args.file.read_text())
    endpoint_name = error.get("endpoint_name")
    if not endpoint_name:
        print("Error: no endpoint_name found in error file", file=sys.stderr)
        sys.exit(1)

    # Extract request from request_json (toJSONString output) or request
    request = {}
    if "request_json" in error:
        request = json.loads(error["request_json"])
    elif "request" in error:
        request = error["request"] if isinstance(error["request"], dict) else {}

    # Apply gap adjustment first
    if args.gap:
        apply_gap(request, parse_duration(args.gap), endpoint_name)

    # Apply overrides
    for kv in args.set:
        key, _, value = kv.partition("=")
        if not _:
            print(
                f"Error: invalid --set format '{kv}', expected key=value",
                file=sys.stderr,
            )
            sys.exit(1)
        request[key] = value

    # Apply deletions
    for key in args.delete:
        request.pop(key, None)

    print(f"Endpoint:   {endpoint_name}", file=sys.stderr)
    print(f"Request: {json.dumps(request, indent=2)}", file=sys.stderr)

    # ...load host + token from token file...
    host, token = parse_token(token_path)
    headers = {"Authorization": f"Bearer {token}"}

    # Explain mode: hit /explain for each cte
    if args.explain:
        ctes = discover_ctes(endpoint_name)
        if not ctes:
            # ...error + exit if no .endpoint file found...
            sys.exit(1)

        explain_dir = args.file.parent / f"{args.file.stem}_explain"
        explain_dir.mkdir(parents=True, exist_ok=True)

        print(f"Explaining {len(ctes)} ctes...", file=sys.stderr)
        for cte in ctes:
            resp = httpx.post(
                f"{host}/v0/endpoints/explain",
                json=request,
                headers=headers,
                timeout=60,
            )
            out_path = explain_dir / f"{cte}.json"
            try:
                result = resp.json()
                out_path.write_text(json.dumps(result, indent=2, default=str))
            except json.JSONDecodeError:
                out_path.write_text(resp.text)
            status = "ok" if resp.is_success else str(resp.status_code)
            print(f"  {cte}: {status}", file=sys.stderr)

        print(f"Explain output written to {explain_dir}/", file=sys.stderr)

    # Replay: POST to the endpoint
    response = httpx.post(
        f"{host}/v0/endpoints/{endpoint_name}",
        json=request,
        headers=headers,
        timeout=60,
    )

    print(f"Status: {response.status_code}", file=sys.stderr)

    try:
        result = response.json()
        output = json.dumps(result, indent=2, default=str)
    except json.JSONDecodeError:
        output = response.text

    if args.output:
        args.output.write_text(output)
        print(f"Written to {args.output}", file=sys.stderr)
    else:
        print(output)

I have two arguments for why this is bad:

1. You can’t quickly skim this to get the function’s story. If I have to spend more than 5 seconds making heads or tails of what something does, it’s usually too big or poorly structured.⁹
2. If you want to change this, you have to keep a lot of different requirements in your head to make sure nothing breaks when adding a new thing. I acknowledge that sometimes that’s a feature, not a bug.

Here’s the whole thing afterward:

def main():
    # ...same argparse setup...
    args = parser.parse_args()

    if not args.file.exists():
        print(f"Error: {args.file} not found", file=sys.stderr)
        sys.exit(1)

    endpoint_name, request = load_error_request(args.file)

    if args.gap:
        apply_gap(request, parse_duration(args.gap), endpoint_name)
    apply_overrides(request, args.set, args.delete)

    print(f"Endpoint:   {endpoint_name}", file=sys.stderr)
    print(f"Request: {json.dumps(request, indent=2)}", file=sys.stderr)

    # ...load host + token from token file...
    host, token = parse_token(token_path)
    headers = {"Authorization": f"Bearer {token}"}

    if args.explain:
        run_explain(host, headers, endpoint_name, request, args.file)

    run_replay(host, headers, endpoint_name, request, args.output)

Here’s another example that surprised me¹⁰, this time from mdlr’s own codebase. These test cases all repeated the same test setup code, which was surfaced via the code duplication metric.

Before:

#[test]
fn test_load_from_current_dir() {
    let temp = TempDir::new().unwrap();
    let config_dir = temp.path().join(".mdlr");
    fs::create_dir(&config_dir).unwrap();
    fs::write(
        config_dir.join("config.yaml"),
        r#"
thresholds:
  dag_density:
    excellent: 0.3
    good: 0.8
    fair: 1.2
    poor: 1.8
"#,
    )
    .unwrap();

    let config = load_from_dir(temp.path()).unwrap();
    assert_eq!(config.thresholds.dag_density.excellent, 0.3);
    // Defaults still work for unspecified fields
    assert_eq!(config.thresholds.fan_in_max.excellent, 3.0);
}

#[test]
fn test_load_disabled_metrics() {
    let temp = TempDir::new().unwrap();
    let config_dir = temp.path().join(".mdlr");
    fs::create_dir(&config_dir).unwrap();
    fs::write(
        config_dir.join("config.yaml"),
        r#"
disabled_metrics:
  - lcom
  - duplication_pct
"#,
    )
    .unwrap();

    let config = load_from_dir(temp.path()).unwrap();
    assert!(config.is_disabled("lcom"));
    assert!(config.is_disabled("duplication_pct"));
    assert!(!config.is_disabled("cyclomatic"));
}

// ...and a third test with the same setup block...

After:

/// Write `.mdlr/config.yaml` under `root` with the given contents.
fn write_config(root: &Path, yaml: &str) {
    let config_dir = root.join(".mdlr");
    fs::create_dir_all(&config_dir).unwrap();
    fs::write(config_dir.join("config.yaml"), yaml).unwrap();
}

#[test]
fn test_load_from_current_dir() {
    let temp = TempDir::new().unwrap();
    write_config(
        temp.path(),
        r#"
thresholds:
  dag_density:
    excellent: 0.3
    good: 0.8
    fair: 1.2
    poor: 1.8
"#,
    );

    let config = load_from_dir(temp.path()).unwrap();
    assert_eq!(config.thresholds.dag_density.excellent, 0.3);
    // Defaults still work for unspecified fields
    assert_eq!(config.thresholds.fan_in_max.excellent, 3.0);
}

#[test]
fn test_load_disabled_metrics() {
    let temp = TempDir::new().unwrap();
    write_config(
        temp.path(),
        r#"
disabled_metrics:
  - lcom
  - duplication_pct
"#,
    );

    let config = load_from_dir(temp.path()).unwrap();
    assert!(config.is_disabled("lcom"));
    assert!(config.is_disabled("duplication_pct"));
    assert!(!config.is_disabled("cyclomatic"));
}

mdlr’s goal isn’t to be an authority on what makes code good. I’m also not making the claim that optimizing software metrics will automatically give you perfectly clean code. The goals here are

1. Provide a tool that enables agents to think a little more like we do.
2. Provide a tool that enables agents to produce directionally better code.
3. Get people thinking more about the boundaries between what agents should do versus what traditional engineering can do.

I’m not convinced¹¹ that today’s agents are the final answer. The idea that we all just have to spin up as many agents as humanly possible to craft our world and review our work feels odd, especially when cheap deterministic tools can be so successful.

You can find mdlr on GitHub: github.com/thempatel/mdlr. Use it! Then come back and tell me what you think.

During college, I like many of my peers, decided that medical school was what I wanted to pursue. After 4 years of many sleepless nights, many extracurriculars (including a part-time job as a computer tech, some late night EMT shifts, scientific research and volunteer work abroad) I faced rejection from all 26 medical schools that I had applied to. Ouch.

I needed something to bide my time while I reapplied the following cycle but unfortunately, the only job I could find was as a barista at the very school I had just graduated from. This was humbling: while many of my peers had moved on to start their next big thing, I was still at the same institution, serving many of my younger peers who had yet to graduate.

Around the same time, I had interviewed at the Centers for Disease Control and Prevention for a job as a data manager. I was rejected. I was honest in the interview that I was only looking for a gap-year job before heading to medical school and they needed someone to stick around longer than that, so the timing just didn’t work out.

Fast forward a few grueling months and I got a call back from the same division I had interviewed with. Another team was in the market for someone who could work part-time for a short term project as a stool collector for a double-blind study they were about to setup. Yep, you read that right.

At the time I was desperate for any kind of job that would help make my resume stand out to medical schools in the following cycle and the 20 hours there would pay the same as what I was earning doing 40 at the coffee shop. Knowing that I also had to set myself up for financial success, I decided to do both: I would block off 20 hours during the week to make ends meet at the CDC and use the rest for shifts at the coffee shop.

There was some stipulation during the interview that I’d get to work with computers in addition to collecting stool which turned out, at least in the early stages, to not be the case. Although it had been a step up from the coffee shop in terms of prestige, I still had not achieved the impact I was searching for. During those 20 hours, I tried to be a go-getter: I went out of my way to find as many non-stool collecting opportunities as possible, hoping that the stars would align somehow, somewhere.

Eventually, one of my team leads gave me a project I’m sure she thought would keep me busy for a while. She was working on a project where she needed to figure out the ideal gene sequences to build an assay with, and a colleague helping her with the task was going through a huge spreadsheet filled with protein references and manually tagging them with metadata from NCBI. I’m not sure what exactly led her to ask me to work on it instead but at the time I didn’t ask too many questions.

Tagging all the proteins by hand would’ve taken weeks but it turned out that NCBI had a public API that could be used to fetch the information. I had some minimal experience with Python and I knew no one was really expecting the results for a while, so I decided to see if I could code something up. Three days later, I had a well fleshed out spreadsheet with thousands of tagged gene sequences and a sense of accomplishment.

In the following weeks, my team lead presented her work and mentioned that they were able to put everything together so fast because I had scripted something up to do all the hard parts. To my great fortune, her boss was there to hear the success and as it turned out, was in need for someone who could program in Python. I was promptly signed up for another 20 hours to come work for her, giving me 40 hours at the CDC. I consequently left my job as a barista.

I spent the next 2 years as a coding bootcamp-er of sorts. It was the best possible situation: during the evenings I’d study up on Python, engineering, and computer science fundamentals and during the day I’d get to apply the knowledge, slowly honing my craft. Through a series of epiphanies I realized that becoming a doctor wasn’t what I really wanted to do with my life. I also knew that I wanted to work as a software engineer in industry and the CDC wasn’t going to help me meet that long term goal, so I left for a contract software gig and the rest is history.

This anecdote is only the beginning of how I got to where I am today. I feel so fortunate to be born during such a vibrant period of human history. One where the democratization of knowledge has allowed many stories like mine to exist. My advice to you is this: dream big, take leaps of faith and don’t look back. You get one life, make the most of it!