Comment by simonw | Hacker News Reader

Comment by simonw | Hacker News Reader

Parent Full thread

- Good automated tests which the coding agent can run. I love pytest for this - one of my projects has 1500 tests and Claude Code is really good at selectively executing just tests relevant to the change it is making, and then running the whole suite at the end

- 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.

> I actually don't think documentation is too important

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.

I don't even bother pasting issues.

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.

Regarding documentation, I’d love to hear you take on creating the CLAUDE.md/AGENTS.md type of files using the tools themselves, typically via some /init command. I think Claude Code, Codex and Copilot CLI all have a similar thing.

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 have to admit I don't actually use those yet - I've been enjoying learning how to succinctly prompt in a way that gets the right results without them.

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

This is covered in the Claude Code docs here: https://docs.claude.com/en/docs/claude-code/claude-code-on-t...

My issue with that is that I don't really have any Python tooling installed globally (old trauma with overlapping package versions), each project is in an uv venv.

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

Reply on news.ycombinator.com