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

Sasha Levin
2025-07-28T12:35:42Z

On Sun, Jul 27, 2025 at 11:18:14PM -0700, Kees Cook wrote:
>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.

But my point is that calling /init is a prompt (just one hidden behide
the scenes).

Without an explicit /init call and no CLAUDE.md (or the copilot/cursor
equivalents which I've tested), nothing reads README.

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

Oh, this is interesting!

Do you see it being as something like "Common kernel usage usecases" and
then some sort of a tree of docs/blurb related to those uses?

Sort of like a meta-index that indexes the docs by purpose rather than
their location in the directory?

Do you see it as being just links to existing docs or should it have
some blurb in addition to the links?

--
Thanks,
Sasha