Re: [PATCH 2/4] agents: add core development references

[Kees Cook <kees@kernel.org>]

On Mon, Jul 28, 2025 at 01:59:42AM -0400, Sasha Levin wrote:
> Thing is, agents won't read the README on their own: they need to be
> prompted to do it.

Claude does:

 > /init

● I'll analyze the codebase and create a CLAUDE.md file to help future
  instances of Claude Code work effectively in this repository.

● Update Todos
  ⎿  ☐ Analyze codebase structure and files
     ☐ Check for existing CLAUDE.md file
     ☐ Look for build/test/lint configuration files
     ☐ Create CLAUDE.md file
     ☐ Examine README and other documentation
     ☐ Check for Cursor/Copilot rules
...
● Read(Makefile)
  ⎿  Read 50 lines (ctrl+r to expand)
...

Even before having read any file at all, Claude calls out README as a
place to look.

And in the resulting CLAUDE.md:

## Documentation

Primary documentation is in Documentation/ directory:
- **Documentation/admin-guide/**: System administration
- **Documentation/driver-api/**: Device driver APIs
- **Documentation/core-api/**: Core kernel APIs
- **Documentation/process/**: Development process guidelines


> I'm assuming we both agree that we need to give the agent some entry
> point which they will automatically process without any user prompts,
> even if it's just saying "Please read the README file!"?

I'm saying any agent that can be expected to work on Linux should already
be trying to read the README. But regardless, both Makefile comments and
"make help" output say to read the README, so we should fix it for
humans too.

> I think it'll be hard to find a common path that works here. README is
> pretty generic because there are different humans that might read it:
> 
>  - A university researcher who should be pointed to researcher-guidelines.rst
>  - A security researcher who should be pointed to security-bugs.rst or embargoed-hardware-issues.rst
>  - A newbie trying to set up his mail client and needs to be pointed to email-clients.rst
>  - A coding agent that doesn't care about none of the above.
> 
> So we can clean up README and try to make it an entry point that will
> fit most of it's potential readers, but I worry that at the end it will
> end fitting none of them.

I think the above list is perfect contents for the README. Yes, please
make that an entry point, or point to some other .rst entry point that
will have a list of roles like that, with some common starting points.
And yes, a line for agents in there seems fine. Maybe "If you are a
coding agent, also see ... for agent-specific details."

> Without crafting something more specific for agents, I also worry that
> we'll be stuffing the limited context they already have with information
> that will only hurt their performance (just like humans: there's only so
> much we can remember at a time).

Sure, but these things will only get better, and I'd rather spend the
time making the docs better for humans. Each agent will latch on to
different things it assumes is important -- the developer will need to
correct them no matter what. An agent isn't going to be acting alone
(yet).

-Kees

-- 
Kees Cook