Add CLAUDE.md agent file

[jakecorrenti]

Add a CLAUDE.md file to give Claude persistent context about libkrun. This includes project structure, coding standards, and workflows we prefer.

This was initially generated by running /init inside of Claude Code. I took some sections from
https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md?plain=1 and
https://github.com/openai/openai-agents-python/blob/f20aa40f56ec374841dfe6e4f3d6118c8e32fb2b/AGENTS.md.

This should be a living document that we adjust and modify as time goes on to better improve the agentic workflow.

I would love to get some discussion going about a couple things:

• What would people like to add
• What would people like to remove
• How is the formatting
• How do we handle multiple agent files? Claude doesn't support AGENTS.md, but we could have one AGENTS.md that we symlink to from the other files.

[jakecorrenti]

I've also been using the Superpowers Claude plugin which has been useful.

I also want to experiment with Personas to see if that has any workflow improvement as well. If anyone has any other cool plugins/configurations I'd be interested to hear about those here as well.

[mtjhrc]

The project overview and information about running tests is definitely something we should have in a commited AGENTS.md and looks useful!

I am not a fan of committing some the general Claude "workflow" sections here however.

Also imagine someone want to override them, because they don't like them for some reason or it doesn't work well with their LLM, then it will become super annoying for them to not be able to use the project provided AGENTS.md at all and having to configure something to ignore them.

How do we handle multiple agent files? Claude doesn't support AGENTS.md, but we could have one AGENTS.md that we symlink to from the other files.

I would strongly prefer AGENTS.md and point CLAUDE.md to it. I think you can just put @AGENTS.md into a CLAUDE.md file and it would work.

[mtjhrc]

So this section comes from my CLAUDE.md, but I am not sure if we should include it fully verbatim in the committed version.

This is also perhaps bit of workflow thing too. Though it's also a bit specific to things I found Claude (at least in the past) struggle with in libkrun. But if you test the code you submit you, you would notice your change doesn't actually work and just deadlocks immediately.

The more I think about this I realize there is sort of a tradeoff here. If we put a lot of these guidelines here it could be annoying for people that have their own guidelines like this. However it would be really beneficial for people with default agents configuration especially if they are inexperienced or don't notice the issues produced by the agent - I can see this improving the quality of random drive-by PRs.

Maybe a middle-ground could be to keep this section but shorten it?

[mtjhrc]

@jakecorrenti Have you noticed Claude or other LLMs also struggle with this? If not maybe we should hold off on this for now?

[jakecorrenti]

I don't think I've run into that personally. The one thing I've been running into a lot is the agent basically liking to hear itself talk. i.e.

fn foo() {
    bar();
}

fn bar() {
   foobar();
}

fn foobar() {
    println!("Hello, world!");
}

[lstocchi]

@jakecorrenti have you read this best practice doc? There are some interesting tips related to the AGENTS file.