{"slug": "lukewarm-recommendations-for-improving-ai-agents-interactions-with-your-projects", "title": "Lukewarm recommendations for improving AI agents' interactions with your projects", "summary": "Renovate maintainer Jamie Tanna published a set of \"lukewarm\" recommendations for improving AI agents' interactions with codebases, drawn from Renovate's experience accepting AI contributions since mid-2025. The recommendations center on a lightly maintained AGENTS.md/CLAUDE.md that points agents to existing human-facing development-standards docs rather than duplicating them, and a single `pnpm check` command that runs the same checks as CI, optionally against modified files or with `--no-test`. Tanna said agents largely produced technically correct code before any explicit optimization, crediting Renovate's predictable structure and contributor documentation, and argued that agents producing code that fails project checks wastes maintainers' time.", "body_md": "Over the last week I've been chatting with some folks who are looking at integrating AI more into their development work. I shared a couple of things that we've found have worked well for [Renovate](https://docs.renovatebot.com/), as a codebase that takes a lot of human (and since mid-last year, AI) contributions.\n\nAlthough I've written about this [a bit in my reflection on the last year](https://www.jvt.me/posts/2026/09/21/renovate-1-year/#improving-life-for-agents-and-humans), this naturally deserves its own [blogumentation](https://www.jvt.me/posts/2017/06/25/blogumentation/).\n\nBefore we did anything to explicitly optimise the codebase for AI agents, we ended up finding that we'd - for the most part - receive fairly technically correct code, although it wouldn't necessarily fit in the areas that it was added for, or wouldn't completely fit our code style, but would handle a lot of file-directory architecture choices.\n\nWe credit this down to the fact that we've structured our codebase in a predictable and - in my opinion, reasonable - structure, which has been optimised for the humans who are interacting with it. As well as this, we've also had documentation for new contributors to understand how best to get started, which also helps the agents!\n\nI've called this a \"lukewarm\" set of recommendations because for anyone who's fairly invested in doing work with AI agents, these are going to feel like so last `$timePeriod`. I appreciate that they're not ground breaking, but they're useful for folks who may be earlier in their AI journey than others.\n\nThese recommendations build on great work that [Sergei Zharinov](https://github.com/zharinov) and [Sebastian Poxhofer](https://secustor.dev) - as well as a few other folks - have been doing.\n\n`AGENTS.md` / `CLAUDE.md`\nI'm largely adding this for completeness - it's a fairly standard recommendation that you'll get from most people, but the interesting angle we've got is that it doesn't need to be exhaustive.\n\nYou can see that [we've barely updated `AGENTS.md` since adding it in May](https://github.com/renovatebot/renovate/commits/main/AGENTS.md), but [we have made many docs edits for our \"development standards\" documentation](https://github.com/renovatebot/renovate/commits/main/docs/development?since=2026-05-18&until=2026-10-24).\n\nThese docs were originally built for human readers, and are still our recommended area for this information to sit, but agents are told - via the `AGENTS.md` - that they should read it, so we're not duplicating information.\n\n`check` script\nHaving a single command to run to know \"these changes pass the same checks that would run in CI\" is really useful. Since adding this to Renovate, I've ended up needing a similar command across all of my projects because the muscle memory of it is as powerful as it is useful.\n\nWe'll run this as i.e.\n\n```\n# all checks\npnpm check\n# run against modified files (and their associated tests)\npnpm check lib/renovate.ts lib/manager/.../artifacts.ts\n# don't run tests (useful when you've run the tests on the affected file separately)\npnpm check --no-test\n\n# make sure that each commit builds atomically\n# where `gch` is a utility to list what files changed in the last commit\ngit rebase -i origin/HEAD -x 'pnpm check $(gch)'\n```\n\nThis is particularly handy when you're jumping between different projects and you're trying to remember whether it's `pnpm run ...` or `npm run ... && npm run ...` or `make ...` or `just ...`, and means you're down to a single consistent command to remember.\n\nThis is - in my opinion - more useful for the humans, as they feel the pain of needing to remember things more than the agents.\n\nIn my experience, if you have an agent that produces code that doesn't actually pass the project's automated checks - especially if you're *intentionally* not running them - it's a waste of your and the maintainer's time.\n\nAs much as we can try and recommend people run the checks they need to, some won't do - so we add a [`Stop` hook](https://code.claude.com/docs/en/hooks#stop) for Claude Code to make sure that the agent has run `pnpm check` before it says it's \"finished\" on a piece of work.\n\nThis means that Claude Code may think it's written the code it needs to, but then `pnpm check` will flag that there's a test failure, or a linting rule doesn't like that you're using `new Number(...)`, and Claude Code will continue through its loop until it's passing all checks.\n\n(We currently optimise for Claude Code, but should look at a similar for other agent harnesses)\n\nIn practice, we've found that this ends up producing much better code, as we're making sure that more and more common concerns are caught in the `check` command.\n\nA lot of common nitpicks, or \"can you please do ... instead\" comments in code review should ideally be moved into linting rules, so a (human) reviewer can focus on the more important factors when reviewing the changes.\n\nSebastian's been leading the efforts to analyse our code review comments and convert the most common issues into linting rules, where possible, which has improved the quality of the code coming into the project from humans and agents alike.\n\n`mise` (or an alternative)\nIn the Node.JS world, we do have some controls in place to make it more straightforward for a user to know that they need [a given version of Node.JS or `pnpm`](https://github.com/renovatebot/renovate/blob/9e0bc64e3e524ca92044404406cea1e12a8df551/package.json#L150-L153) to work with the project, provided folks read our `package.json` or development documentation.\n\nThis is something we've generally kept documented - and historically used [Volta.sh](https://github.com/volta-cli/volta), [until it was unmaintained](https://github.com/renovatebot/renovate/pull/40567) - as we aim to make it straightforward for new contributors to get started.\n\nFor contributions via agents, we decided to be even more strict, by capturing our tool requirements with [mise-en-place (`mise`)](https://mise.jdx.dev/) and adding [a `PreToolUse` Hook](https://code.claude.com/docs/en/hooks#pretooluse) (for Claude Code).\n\nWith this, there's a consistent set of tools that humans and agents alike can know are recommended to use with the project, and if an agent tries to i.e. run `npm install`, it'll get told \"no, we use `pnpm install`\", or if trying to use `pnpm jest` we'll correct it to `pnpm vitest`.\n\nThis also means that if you're running Cloud-based agents, they need much less pre-installed, and can only require `mise` to get started.\n\nI've recently been using [Amp](https://ampcode.com), given [you can now use your Claude subscription with it](https://ampcode.com/news/use-your-claude-plan). I've been enjoying it so far, and finding that the way the agent frames its changes (and associated tradeoffs) to be nicer than what I've been seeing with Claude Code.\n\nHowever, I've noticed that the resulting code from Amp's Claude Opus isn't as \"nice\" as Claude Code's Claude Sonnet would output, which is surprising.\n\nI'm sure there's something that I need to do to tune Amp a little better, but I've found that when Amp is finished, asking for a Claude Sonnet subagent (or spinning up a separate Claude Code with Sonnet) to review and improve the code will result in a better overall result, albeit it spends more tokens.\n\nDid you notice that a lot of the above changes are things that also help the humans? Funny how that works out.\n\nI strongly recommend that you remember that - at least for now? - there are humans in the loop, who deserve documentation. They always should have had documentation to read through and understand how to get started, solve specific problems, and how the project approaches its design and architecture, but we now see a lot more of this happening because \"the agents need it\", as if the humans didn't.\n\nRemember that if you optimise for human-facing documentation, tools and utilities, these will generally be useful for the agents, who've been trained on so many millions of hours of our collective work.", "url": "https://wpnews.pro/news/lukewarm-recommendations-for-improving-ai-agents-interactions-with-your-projects", "canonical_source": "https://www.jvt.me/posts/2026/10/25/renovate-agent-improvements/?utm_medium=rss&utm_source=rss", "published_at": "2026-10-25 17:25:54+00:00", "updated_at": "2026-10-25 18:11:10.600870+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools"], "entities": ["Renovate", "Jamie Tanna", "Sergei Zharinov", "Sebastian Poxhofer"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/lukewarm-recommendations-for-improving-ai-agents-interactions-with-your-projects", "markdown": "https://wpnews.pro/news/lukewarm-recommendations-for-improving-ai-agents-interactions-with-your-projects.md", "text": "https://wpnews.pro/news/lukewarm-recommendations-for-improving-ai-agents-interactions-with-your-projects.txt", "jsonld": "https://wpnews.pro/news/lukewarm-recommendations-for-improving-ai-agents-interactions-with-your-projects.jsonld"}}