4 ms·

On the other hand, AI coding tools make it relatively easy to set and apply policies that can help with this sort of thing. I like to have something like the f

On the other hand, AI coding tools make it relatively easy to set and apply policies that can help with this sort of thing. I like to have something like the following in AGENTS.md: ## Guiding Principles - Optimise for long-term maintainability - KISS - YAGNI

shafyy 7mo ago
Not sure if you're kidding or not, but to write great maintable code, you need a lot of understanding that a LLM just doesn't have, like history, business context, company culture etc. Also, I doubt that in it's training data it has a lot of good examples of great maintainable code to pull from.
- nhayfield 7mo ago
  He isn't kidding. I have a directive to write the shortest, least complicated, readable business code and it makes a huge difference
  - kurthr 7mo ago
    Sometimes, as in the bilsbi's top level comment, the solution is to use a free tool/library/product that already exists. The solution is not always to write new code, but the agent will happily do it. Maybe that's "the manager's job", but that's just passing the buck and getting a worse solution. Every level of management should be looking for the best solution.
- yudhiyudhi 7mo ago
  Neither do most humans writing such code, i have seen llms generate better code than 90% of coders I have seen in the last 20 years
  - forgetfreeman 7mo ago
    Admitting you've spent two decades on a career stuck working in the kind of sweatshops that hire people who can't actually code isn't much of a flex, and certainly doesn't lend a whole lot of credence to your argument.
    - zelphirkalt 7mo ago
      Not the GP, but when I take strolls through some open source project hosted on GitHub, usually I am not impressed either. Unnecessary OOPism, way too long procedures, that instead could be pure functions, badly named variables, and way, way, waaay too many willy-nilly added dependencies. If that is what the LLMs mostly learn from, I am not surprised at all. But then again this stuff was also written by humans. I remember one especially bad case of a procedure in a very popular project (in its niche) that was basically a 1 man show. A procedure of 300+ lines doing all kinds of stuff, changing the global state of that service it is implementing. But that code was or is relied upon by tech giants and other businesses and no one improves it. They are happy with paying that one guy probably not so much money.
  - shimman 7mo ago
    This says more about you and the people you work with. I find engineers that have been at the company for a while are quite invaluable when it comes to this information, it's not just knowing the how but the when + why that's critical as well. Acting like people can't be good at their job is frankly dehumanizing and says a lot about your mindset with how you view other fellow devs.
    - zelphirkalt 7mo ago
      If only more engineers admitted, that something they wrote is not good code, but a product of its time, then I think we would get more realistic expectations. It's OK to say that something you made is shit. It is OK to say that you were not given time to do xyz. How you recognize something has been made fitting at least is, when you see it in use without much of a change for some 3 or 4 years and while you are the person maintaining it, you rarely ever need to touch it, because you built it in a way that is simple enough to not have tons of bugs yet flexible enough, to cover use-cases and anticipated use-cases.
  - shafyy 7mo ago
    Please let's stop with the "but some humans also suck at this so it's ok if LLMs also suck at it" argument. It doesn't add anything to the discussion.
  - Thanemate 7mo ago
    Awesome! However, the corporate is excited with using AI, making the coder the one who's at risk at getting fired for writing the exact same lousy (for the sake of the argument) code. Or worse: for not relying as much as possible to the AI who apparently can write just as bad code but faster! A subtle detail: you speak of coders, not software engineers. A SWE's value is not his code churning speed.
- whattheheckheck 7mo ago
  "Be sure to remember software is a sociotechnical system and dont fall prey to the Mechanistic myth"
musesum 7mo ago
I wrote something similar in a Claude Code instructions.md: "minimize cyclomatic complexity" What happened next? It generated an 8 line wrapper function called only once from a different file. So, I told it to inline that logic in the caller. The result? One. Line. Of. Code. So, I asked it to modify its instructions.md file to not repeat that mistake. The result was the new line "Avoid single-use wrapper functions; inline logic at the call site unless reused" instruction.md is the new intern.
- Cthulhu_ 7mo ago
  It reminds me a lot of people who take Code Complete too seriously. "Common sense" is not an objective or universal statement unfortunately - plus, speaking for myself, what I consider "common sense" can change on the daily, which is why I can't be trusted adding features to my own codebase long term <_<.
musesum 7mo ago
I wrote something similar in a Claude Code instructions.md: "minimize cyclomatic complexity" What happened next? It generated an 8 line wrapper function called only once from a different file. So, I told it to inline that logic in the caller. The result? One. Line. Of. Code. So, I asked it to modify its instructions.md file to not repeat that mistake. The result was the new line "Avoid single-use wrapper functions; inline logic at the call site unless reused" instructions.md is the new intern.
- reedlaw 7mo ago
  Maybe a better way to handle "minimize cyclomatic complexity" would be to set an agent in a loop of code metrics, refactor, test and repeat.
  - musesum 7mo ago
    Good idea. Am still a bit shy around token budget spend.
    - Cthulhu_ 7mo ago
      I think this is at the moment the practical limitation to using AI for everything (and what the coding agents themselves also optimize for to some degree, or it's the slider they can play with for price vs quality, the "thinking" models being the exact same, but just burning more tokens).
      - musesum 7mo ago
        Am waiting for the next Mac Studio to come out to experiment with the "AI for everything" approach. Most likely, the open source distilled models will lower quality. So, another "price vs quality" tradeoff. Still, will be fun to code like I'm at a foundation lab.
    - reedlaw 7mo ago
      This seems like a perfect use case for a local model. But I've found in practice that the system requirements for agents are much higher than for models that can handle simple refactoring tasks. Once tool use context is factored in, there is very little room for models that perform decently.
Niko901ch 7mo ago
This is exactly right. I maintain an AGENTS.md for my own AI assistant with similar principles - "禁止只记录不行动" (no recording without action) and strict rules about when to escalate vs. when to solve autonomously. The key insight is that the AGENTS.md becomes a kind of "engineering culture in a file". When you onboard a human engineer, you hope they absorb the team's values over time. With AI, you can encode those values upfront. The challenge is that principles need to be specific enough to be actionable. "Write simple code" is too vague. "Avoid single-use wrapper functions" (from the sibling comment) is better - it's enforceable.

shafyy 7mo ago

Not sure if you're kidding or not, but to write great maintable code, you need a lot of understanding that a LLM just doesn't have, like history, business context, company culture etc. Also, I doubt that in it's training data it has a lot of good examples of great maintainable code to pull from.

nhayfield 7mo ago
He isn't kidding. I have a directive to write the shortest, least complicated, readable business code and it makes a huge difference
- kurthr 7mo ago
  Sometimes, as in the bilsbi's top level comment, the solution is to use a free tool/library/product that already exists. The solution is not always to write new code, but the agent will happily do it. Maybe that's "the manager's job", but that's just passing the buck and getting a worse solution. Every level of management should be looking for the best solution.
yudhiyudhi 7mo ago
Neither do most humans writing such code, i have seen llms generate better code than 90% of coders I have seen in the last 20 years
- forgetfreeman 7mo ago
  Admitting you've spent two decades on a career stuck working in the kind of sweatshops that hire people who can't actually code isn't much of a flex, and certainly doesn't lend a whole lot of credence to your argument.
  - zelphirkalt 7mo ago
    Not the GP, but when I take strolls through some open source project hosted on GitHub, usually I am not impressed either. Unnecessary OOPism, way too long procedures, that instead could be pure functions, badly named variables, and way, way, waaay too many willy-nilly added dependencies. If that is what the LLMs mostly learn from, I am not surprised at all. But then again this stuff was also written by humans. I remember one especially bad case of a procedure in a very popular project (in its niche) that was basically a 1 man show. A procedure of 300+ lines doing all kinds of stuff, changing the global state of that service it is implementing. But that code was or is relied upon by tech giants and other businesses and no one improves it. They are happy with paying that one guy probably not so much money.
- shimman 7mo ago
  This says more about you and the people you work with. I find engineers that have been at the company for a while are quite invaluable when it comes to this information, it's not just knowing the how but the when + why that's critical as well. Acting like people can't be good at their job is frankly dehumanizing and says a lot about your mindset with how you view other fellow devs.
  - zelphirkalt 7mo ago
    If only more engineers admitted, that something they wrote is not good code, but a product of its time, then I think we would get more realistic expectations. It's OK to say that something you made is shit. It is OK to say that you were not given time to do xyz. How you recognize something has been made fitting at least is, when you see it in use without much of a change for some 3 or 4 years and while you are the person maintaining it, you rarely ever need to touch it, because you built it in a way that is simple enough to not have tons of bugs yet flexible enough, to cover use-cases and anticipated use-cases.
- shafyy 7mo ago
  Please let's stop with the "but some humans also suck at this so it's ok if LLMs also suck at it" argument. It doesn't add anything to the discussion.
- Thanemate 7mo ago
  Awesome! However, the corporate is excited with using AI, making the coder the one who's at risk at getting fired for writing the exact same lousy (for the sake of the argument) code. Or worse: for not relying as much as possible to the AI who apparently can write just as bad code but faster! A subtle detail: you speak of coders, not software engineers. A SWE's value is not his code churning speed.
whattheheckheck 7mo ago
"Be sure to remember software is a sociotechnical system and dont fall prey to the Mechanistic myth"

musesum 7mo ago

I wrote something similar in a Claude Code instructions.md: "minimize cyclomatic complexity" What happened next? It generated an 8 line wrapper function called only once from a different file. So, I told it to inline that logic in the caller. The result? One. Line. Of. Code. So, I asked it to modify its instructions.md file to not repeat that mistake. The result was the new line "Avoid single-use wrapper functions; inline logic at the call site unless reused" instruction.md is the new intern.

Cthulhu_ 7mo ago
It reminds me a lot of people who take Code Complete too seriously. "Common sense" is not an objective or universal statement unfortunately - plus, speaking for myself, what I consider "common sense" can change on the daily, which is why I can't be trusted adding features to my own codebase long term <_<.

musesum 7mo ago

reedlaw 7mo ago
Maybe a better way to handle "minimize cyclomatic complexity" would be to set an agent in a loop of code metrics, refactor, test and repeat.
- musesum 7mo ago
  Good idea. Am still a bit shy around token budget spend.
  - Cthulhu_ 7mo ago
    I think this is at the moment the practical limitation to using AI for everything (and what the coding agents themselves also optimize for to some degree, or it's the slider they can play with for price vs quality, the "thinking" models being the exact same, but just burning more tokens).
    - musesum 7mo ago
      Am waiting for the next Mac Studio to come out to experiment with the "AI for everything" approach. Most likely, the open source distilled models will lower quality. So, another "price vs quality" tradeoff. Still, will be fun to code like I'm at a foundation lab.
  - reedlaw 7mo ago
    This seems like a perfect use case for a local model. But I've found in practice that the system requirements for agents are much higher than for models that can handle simple refactoring tasks. Once tool use context is factored in, there is very little room for models that perform decently.

Niko901ch 7mo ago

This is exactly right. I maintain an AGENTS.md for my own AI assistant with similar principles - "禁止只记录不行动" (no recording without action) and strict rules about when to escalate vs. when to solve autonomously. The key insight is that the AGENTS.md becomes a kind of "engineering culture in a file". When you onboard a human engineer, you hope they absorb the team's values over time. With AI, you can encode those values upfront. The challenge is that principles need to be specific enough to be actionable. "Write simple code" is too vague. "Avoid single-use wrapper functions" (from the sibling comment) is better - it's enforceable.