“and a codebase that’s well setup for it,”
I’d love to see some thought from folks on how to setup a code base to be more productive with AI coding tools.
I’d love to see some thought from folks on how to setup a code base to be more productive with AI coding tools.
- Give them the ability to interactively test the code they are writing too. Notes on how to start a development server (for web projects) are useful, then you can have them use Playwright or curl to try things out
- I'm having great results from maintaining a GitHub issues collection for projects and pasting URLs to issues directly into Claude Code
- I actually don't think documentation is too important: LLMs can read the code a lot faster than you to figure out how to use it. I have comprehensive documentation across all of my projects but I don't think it's the helpful for the coding agents, though they are good at helping me spot if it needs updating.
- Linters, type checkers, auto-formatters - give coding agents helpful tools to run and they'll use them.
For the most part anything that makes a codebase easier for humans to maintain turns out to help agents as well.
Trying to maintain a documentation was actually problematic in a recent project. I made some big changes that were not immediately updated in the documentation; then, in a new session, Claude Code was always referring to the stale markdown documentation file and getting confused about the codebase.
Those often seem to generate a snapshot of the current state of the codebase that to me seem to be just begging to get out of date, often with references to specific files. I sometimes start out with them and remove a bunch of stuff, or I just start empty and add things as they appear to be needed.
What’s your strategy on these?
I've experimented with having LLMs write snippets for them - things like "Based on this session, update AGENTS.md with notes about running the tests" - but my stuff tends to be simple enough that I can just say "Run tests with pytest" and it will know what to do.
I did just confirm that you can use efficiently both AGENTS.md and CLAUDE.md in the same repo by having a CLAUDE.md with a single line:
@AGENTS.md
So every time an LLM starts firing blind they'll go python -> python3 -> damnit -> uv run python, wasting precious tokens.
That's why I have explicit instructions on how to use uv to manage things in AGENTS.md
I just have a /fix-github-issue command that tells Claude to fix issue #xx with some extra definition of done stuff (test + build + update docs before finishing).
I also have a few other /commands for preparing and labeling issues.
Documentation by itself isn't useful (the human-readable kind), but for larger projects it's really useful to have a tree-style description on what is in each directory and a short description on where everything is in general. And this file is specifically LLM-optimised without any extra prose or formatting.
For larger projects you're wasting context if the LLM has to poke around in the dark and guess based on file/class names where everything is.