Skip to contentSkip to conversation

Add unified configuration for coding agents

PATCH In review Sasha Levin 7 participants 14 messages Aug 9, 2025 – Aug 15, 2025

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

v2 cover Add unified configuration for coding agents

This patch series adds unified configuration and documentation for coding agents working with the Linux kernel codebase. As coding agents become increasingly common in software development, it's important to establish clear guidelines for their use in kernel development.

The series consists of two patches:

1. README: restructure with role-based documentation and guidelines
- Reorganizes README to provide targeted documentation paths for different user roles (developers, researchers, security experts, maintainers, and AI coding assistants)
- Adds quick start section and essential documentation links
- Establishes proper attribution requirements for AI-assisted contributions using Assisted-by tags with agent details

2. agents: add unified agent coding assistant configuration
- Creates configuration files for major coding agents (Claude, GitHub Copilot, Cursor, Codeium, Continue, Windsurf, and Gemini)
- Uses @README references to point all agents to the central documentation, ensuring consistency across tools

The agent configuration files now use @README references instead of symlinks.

Example agent attribution in commits:

    Assisted-by: Claude-claude-3-opus-20240229 checkpatch

This ensures full transparency about agent involvement in code development while maintaining proper attribution standards.

Sasha Levin (2):
README: restructure with role-based documentation and guidelines
agents: add unified agent coding assistant configuration

 .codeium/instructions.md        |   1 +
 .continue/context.md            |   1 +
 .cursorrules                    |   1 +
 .github/copilot-instructions.md |   1 +
 .gitignore                      |  10 ++
 .windsurfrules                  |   1 +
 CLAUDE.md                       |   1 +
 GEMINI.md                       |   1 +
 README                          | 184 ++++++++++++++++++++++++++++++--
 9 files changed, 190 insertions(+), 11 deletions(-)
 create mode 100644 .codeium/instructions.md
 create mode 100644 .continue/context.md
 create mode 100644 .cursorrules
 create mode 100644 .github/copilot-instructions.md
 create mode 100644 .windsurfrules
 create mode 100644 CLAUDE.md
 create mode 100644 GEMINI.md
Signature · 1 line
2.39.5
#1 lore raw

PATCH v2 1/2 README: restructure with role-based documentation and guidelines

Reorganize README to provide targeted documentation paths for different user roles including developers, researchers, security experts, maintainers, and AI coding assistants. Add quick start section and essential docs links.

Include proper attribution requirements for AI-assisted contributions using Assisted-by tags with agent details and tools used.

---
 README | 184 +++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 173 insertions(+), 11 deletions(-)
README +173 -11
index fd903645e6de..251677d7cd09 100644
@@ -1,18 +1,180 @@
 Linux kernel
 ============
 
-There are several guides for kernel developers and users. These guides can
-be rendered in a number of formats, like HTML and PDF. Please read
-Documentation/admin-guide/README.rst first.
+The Linux kernel is the core of any Linux operating system. It manages hardware,
+system resources, and provides the fundamental services for all other software.
 
-In order to build the documentation, use ``make htmldocs`` or
-``make pdfdocs``.  The formatted documentation can also be read online at:
+Quick Start
+-----------
 
-    https://www.kernel.org/doc/html/latest/
+* Report a bug: See Documentation/admin-guide/reporting-issues.rst
+* Get the latest kernel: https://kernel.org
+* Build the kernel: make defconfig && make -j$(nproc)
+* Join the community: https://lore.kernel.org/
 
-There are various text files in the Documentation/ subdirectory,
-several of them using the reStructuredText markup notation.
+Essential Documentation
+-----------------------
 
-Please read the Documentation/process/changes.rst file, as it contains the
-requirements for building and running the kernel, and information about
-the problems which may result by upgrading your kernel.
+All users should be familiar with:
+
+* Building requirements: Documentation/process/changes.rst
+* Code of Conduct: Documentation/process/code-of-conduct.rst
+* License: COPYING (GPLv2)
+
+Documentation can be built with make htmldocs or viewed online at:
+https://www.kernel.org/doc/html/latest/
+
+
+Who Are You?
+============
+
+Find your role below:
+
+* New Kernel Developer - Getting started with kernel development
+* Academic Researcher - Studying kernel internals and architecture
+* Security Expert - Hardening and vulnerability analysis
+* Backport/Maintenance Engineer - Maintaining stable kernels
+* System Administrator - Configuring and troubleshooting
+* Maintainer - Leading subsystems and reviewing patches
+* Hardware Vendor - Writing drivers for new hardware
+* Distribution Maintainer - Packaging kernels for distros
+* Agentic Coding - AI assistants working with kernel code
+
+
+For Specific Users
+==================
+
+New Kernel Developer
+--------------------
+
+Welcome! Start your kernel development journey here:
+
+* Getting Started: Documentation/process/development-process.rst
+* Your First Patch: Documentation/process/submitting-patches.rst
+* Coding Style: Documentation/process/coding-style.rst
+* Build System: Documentation/kbuild/index.rst
+* Development Tools: Documentation/dev-tools/index.rst
+* Kernel Hacking Guide: Documentation/kernel-hacking/hacking.rst
+* Core APIs: Documentation/core-api/index.rst
+
+Academic Researcher
+-------------------
+
+Explore the kernel's architecture and internals:
+
+* Researcher Guidelines: Documentation/process/researcher-guidelines.rst
+* Memory Management: Documentation/mm/index.rst
+* Scheduler: Documentation/scheduler/index.rst
+* Networking Stack: Documentation/networking/index.rst
+* Filesystems: Documentation/filesystems/index.rst
+* RCU (Read-Copy Update): Documentation/RCU/index.rst
+* Locking Primitives: Documentation/locking/index.rst
+* Power Management: Documentation/power/index.rst
+
+Security Expert
+---------------
+
+Security documentation and hardening guides:
+
+* Security Documentation: Documentation/security/index.rst
+* LSM Development: Documentation/security/lsm-development.rst
+* Self Protection: Documentation/security/self-protection.rst
+* Reporting Vulnerabilities: Documentation/process/security-bugs.rst
+* CVE Procedures: Documentation/process/cve.rst
+* Embargoed Hardware Issues: Documentation/process/embargoed-hardware-issues.rst
+* Security Features: Documentation/userspace-api/seccomp_filter.rst
+
+Backport/Maintenance Engineer
+-----------------------------
+
+Maintain and stabilize kernel versions:
+
+* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst
+* Backporting Guide: Documentation/process/backporting.rst
+* Applying Patches: Documentation/process/applying-patches.rst
+* Subsystem Profile: Documentation/maintainer/maintainer-entry-profile.rst
+* Git for Maintainers: Documentation/maintainer/configure-git.rst
+
+System Administrator
+--------------------
+
+Configure, tune, and troubleshoot Linux systems:
+
+* Admin Guide: Documentation/admin-guide/index.rst
+* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst
+* Sysctl Tuning: Documentation/admin-guide/sysctl/index.rst
+* Tracing/Debugging: Documentation/trace/index.rst
+* Performance Security: Documentation/admin-guide/perf-security.rst
+* Hardware Monitoring: Documentation/hwmon/index.rst
+
+Maintainer
+----------
+
+Lead kernel subsystems and manage contributions:
+
+* Maintainer Handbook: Documentation/maintainer/index.rst
+* Pull Requests: Documentation/maintainer/pull-requests.rst
+* Managing Patches: Documentation/maintainer/modifying-patches.rst
+* Rebasing and Merging: Documentation/maintainer/rebasing-and-merging.rst
+* Development Process: Documentation/process/maintainer-handbooks.rst
+* Maintainer Entry Profile: Documentation/maintainer/maintainer-entry-profile.rst
+* Git Configuration: Documentation/maintainer/configure-git.rst
+
+Hardware Vendor
+---------------
+
+Write drivers and support new hardware:
+
+* Driver API Guide: Documentation/driver-api/index.rst
+* Driver Model: Documentation/driver-api/driver-model/driver.rst
+* Device Drivers: Documentation/driver-api/infrastructure.rst
+* Bus Types: Documentation/driver-api/driver-model/bus.rst
+* Device Tree Bindings: Documentation/devicetree/bindings/
+* Power Management: Documentation/driver-api/pm/index.rst
+* DMA API: Documentation/core-api/dma-api.rst
+
+Distribution Maintainer
+-----------------------
+
+Package and distribute the kernel:
+
+* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst
+* ABI Documentation: Documentation/ABI/README
+* Kernel Configuration: Documentation/kbuild/kconfig.rst
+* Module Signing: Documentation/admin-guide/module-signing.rst
+* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst
+* Tainted Kernels: Documentation/admin-guide/tainted-kernels.rst
+
+Agentic Coding
+--------------
+
+Essential guidelines for AI coding assistants:
+
+* How to Do Kernel Development: Documentation/process/howto.rst
+* Coding Style: Documentation/process/coding-style.rst
+* Submitting Patches: Documentation/process/submitting-patches.rst
+* Submit Checklist: Documentation/process/submit-checklist.rst
+* Programming Language: Documentation/process/programming-language.rst
+
+Critical Requirements:
+
+* License: Use proper SPDX identifiers per
+  Documentation/process/license-rules.rst; kernel code is generally
+  GPL-2.0-only unless documented exceptions apply (see COPYING)
+* Signed-off-by: Agents MUST NOT add Signed-off-by tags
+  (Only humans can legally certify code submission rights)
+* Attribution: Agents MUST add Assisted-by tag:
+  Assisted-by: $AGENT_NAME-$AGENT_MODEL-$AGENT_VERSION $TOOL1 $TOOL2 ...
+  Examples:
+  - Assisted-by: Claude-claude-3-opus-20240229 checkpatch git-bisect
+  - Assisted-by: GitHub-Copilot-GPT-4-v1.0.0 coccinelle sparse
+
+
+Communication and Support
+=========================
+
+* Mailing Lists: https://lore.kernel.org/
+* IRC: #kernelnewbies on irc.oftc.net
+* Bugzilla: https://bugzilla.kernel.org/
+* MAINTAINERS file: Lists subsystem maintainers and mailing lists
+* Email Clients: Documentation/process/email-clients.rst
Signature · 1 line
2.39.5
maintainer
#2 lore raw

Re: [PATCH v2 1/2] README: restructure with role-based documentation and guidelines

Quoted 7 lines · Sasha Levin

Reorganize README to provide targeted documentation paths for different user roles including developers, researchers, security experts, maintainers, and AI coding assistants. Add quick start section and essential docs links.

Include proper attribution requirements for AI-assisted contributions using Assisted-by tags with agent details and tools used.

Nicely done.

Perhaps the 'Assisted-by:' tag should not be limited to AI assistance but could also be used when accepted notes were given on any revised patch submission.

Oh, and maybe a checkpatch update like this?

---
 scripts/checkpatch.pl | 1 +
 1 file changed, 1 insertion(+)
scripts/checkpatch.pl +1 -0
index e722dd6fa8ef3..d17661141da79 100755
@@ -641,6 +641,7 @@ our $signature_tags = qr{(?xi:
 	Reviewed-by:|
 	Reported-by:|
 	Suggested-by:|
+	Assisted-by:|
 	To:|
 	Cc:
 )};
author Reviewed-by Developer A
#3 lore raw

Re: [PATCH v2 1/2] README: restructure with role-based documentation and guidelines

Quoted 10 lines · Joe Perches
Quoted 7 lines · Sasha Levin

Reorganize README to provide targeted documentation paths for different user roles including developers, researchers, security experts, maintainers, and AI coding assistants. Add quick start section and essential docs links.

Include proper attribution requirements for AI-assisted contributions using Assisted-by tags with agent details and tools used.

Nicely done.

Thanks Joe!

Quoted 3 lines

Perhaps the 'Assisted-by:' tag should not be limited to AI assistance but could also be used when accepted notes were given on any revised patch submission.

The suggestions from the previous patches around expanding this to be a list of tools rather than just "AI" made sense, this is the example I gave in the cover letter:

	Assisted-by: Claude-claude-3-opus-20240229 checkpatch

I find something like that useful because it tells me from the get-go that the submitter ran checkpatch on it (without having to spend a line in the commit message saying the same).

I'm not sure about mixing human feedback into this, it might be difficult to interpert it later.

It might work more naturally as an extension of Reviewed-by?

Quoted 10 lines

Oh, and maybe a checkpatch update like this?
---
scripts/checkpatch.pl | 1 +

1 file changed, 1 insertion(+)
scripts/checkpatch.pl +0 -0
index e722dd6fa8ef3..d17661141da79 100755

scripts/checkpatch.pl our $signature_tags = qr{(?xi: · line 647

Quoted 7 lines
scripts/checkpatch.pl +1 -0
@@ -641,6 +641,7 @@ our $signature_tags = qr{(?xi:
 	Reviewed-by:|
 	Reported-by:|
 	Suggested-by:|
+	Assisted-by:|
 	To:|
 	Cc:
 )};

Yup, makes sense! I'll start including checkpatch updates going forward.

Signature · 2 lines
Thanks,
Sasha
maintainer
#4 lore raw

Re: [PATCH v2 1/2] README: restructure with role-based documentation and guidelines

Quoted 28 lines · Sasha Levin
Quoted 10 lines · Joe Perches
Quoted 7 lines · Sasha Levin

Reorganize README to provide targeted documentation paths for different user roles including developers, researchers, security experts, maintainers, and AI coding assistants. Add quick start section and essential docs links.

Include proper attribution requirements for AI-assisted contributions using Assisted-by tags with agent details and tools used.

Nicely done.

Thanks Joe!

Quoted 3 lines

Perhaps the 'Assisted-by:' tag should not be limited to AI assistance but could also be used when accepted notes were given on any revised patch submission.

The suggestions from the previous patches around expanding this to be a list of tools rather than just "AI" made sense, this is the example I gave in the cover letter:

	Assisted-by: Claude-claude-3-opus-20240229 checkpatch

I find something like that useful because it tells me from the get-go that the submitter ran checkpatch on it (without having to spend a line in the commit message saying the same).

Quoted 6 lines

I'm not sure about mixing human feedback into this, it might be difficult to interpert it later.

It might work more naturally as an extension of Reviewed-by?

Maybe. Dunno.

Sometimes I just give style suggestions or notes for things I'm cc'd on but I don't really review it as a "Reviewed-by:" tag seems to imply a more formal process.

Quoted 1 line
Quoted 1 line

Oh, and maybe a checkpatch update like this?

[]

Quoted 1 line

scripts/checkpatch.pl

Quoted 1 line
scripts/checkpatch.pl +0 -0

[]

Quoted 10 lines

scripts/checkpatch.pl our $signature_tags = qr{(?xi: · line 647

Quoted 8 lines
scripts/checkpatch.pl +1 -0
@@ -641,6 +641,7 @@ our $signature_tags = qr{(?xi:
 	Reviewed-by:|
 	Reported-by:|
 	Suggested-by:|
+	Assisted-by:|
 	To:|
 	Cc:
 )};

Yup, makes sense! I'll start including checkpatch updates going forward.

If the AI/coding 'Assisted-by:' tag doesn't have an email address, then checkpatch is going to complain anyway.

Something in checkpatch's

# Check signature styles

block starting around line 3040 or so will also need updating.

reviewer Reviewed-by on v2 1/2
#5 lore raw

Re: [PATCH v2 1/2] README: restructure with role-based documentation and guidelines

In reply to Sasha Levin
Quoted 5 lines · Sasha Levin

Reorganize README to provide targeted documentation paths for different user roles including developers, researchers, security experts, maintainers, and AI coding assistants. Add quick start section and essential docs links.

Quoted 8 lines

Include proper attribution requirements for AI-assisted contributions using Assisted-by tags with agent details and tools used.

---
 README | 184 +++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 173 insertions(+), 11 deletions(-)

I like it. Thanks.

Signature · 1 line
~Randy
#6 lore raw

Re: [PATCH v2 1/2] README: restructure with role-based documentation and guidelines

In reply to Sasha Levin

Hi Sasha,

Quoted 9 lines · Sasha Levin

Reorganize README to provide targeted documentation paths for different user roles including developers, researchers, security experts, maintainers, and AI coding assistants. Add quick start section and essential docs links.

Include proper attribution requirements for AI-assisted contributions using Assisted-by tags with agent details and tools used.

Thanks for your patch!

Quoted 4 lines
README +1 -0
 
+Who Are You?

README line 38

Quoted 10 lines
README +10 -0
+============
+
+Find your role below:
+
+* New Kernel Developer - Getting started with kernel development
+* Academic Researcher - Studying kernel internals and architecture
+* Security Expert - Hardening and vulnerability analysis
+* Backport/Maintenance Engineer - Maintaining stable kernels
+* System Administrator - Configuring and troubleshooting
+* Maintainer - Leading subsystems and reviewing patches

Kernel Maintainer?
Driver/Subsystem Maintainer?

README line 41

Quoted 3 lines
README +3 -0
+* Hardware Vendor - Writing drivers for new hardware
+* Distribution Maintainer - Packaging kernels for distros
+* Agentic Coding - AI assistants working with kernel code

Given the extensive split, what about normal (existing) kernel developers?

Gr{oetje,eeting}s,

Geert

Signature · 5 lines
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds
#7 lore raw

Re: [PATCH v2 1/2] README: restructure with role-based documentation and guidelines

Quoted 18 lines · Geert Uytterhoeven

Hi Sasha,

Quoted 9 lines · Sasha Levin

Reorganize README to provide targeted documentation paths for different user roles including developers, researchers, security experts, maintainers, and AI coding assistants. Add quick start section and essential docs links.

Include proper attribution requirements for AI-assisted contributions using Assisted-by tags with agent details and tools used.

Thanks for your patch!

Quoted 2 lines
README +0 -0
Quoted 14 lines

README line 38

Quoted 11 lines
README +11 -0
+Who Are You?
+============
+
+Find your role below:
+
+* New Kernel Developer - Getting started with kernel development
+* Academic Researcher - Studying kernel internals and architecture
+* Security Expert - Hardening and vulnerability analysis
+* Backport/Maintenance Engineer - Maintaining stable kernels
+* System Administrator - Configuring and troubleshooting
+* Maintainer - Leading subsystems and reviewing patches

Kernel Maintainer?
Driver/Subsystem Maintainer?

I tried to use similar terms to the ones used by the rest of our docs. In this case, the CoC interpertation actually defines this term :)

The Code of Conduct uses the term "maintainers" numerous times. In the kernel community, a "maintainer" is anyone who is responsible for a subsystem, driver, or file, and is listed in the MAINTAINERS file in the kernel source tree.

So I just went with "Maintainer".

Quoted 6 lines

README line 41

Quoted 3 lines
README +3 -0
+* Hardware Vendor - Writing drivers for new hardware
+* Distribution Maintainer - Packaging kernels for distros
+* Agentic Coding - AI assistants working with kernel code

Given the extensive split, what about normal (existing) kernel developers?

Those people don't read the docs anyway :p

How about something like:

Existing Kernel Developer
-------------------------

Continue advancing your kernel development expertise:

* Locking and Concurrency: Documentation/locking/index.rst
* RCU (Read-Copy Update): Documentation/RCU/index.rst
* Subsystem APIs: Documentation/driver-api/index.rst
* Performance Analysis: Documentation/trace/index.rst
* Testing Infrastructure: Documentation/dev-tools/testing-overview.rst
* Patch Series Management: Documentation/process/5.Posting.rst
* Maintainer Handbooks: Documentation/process/maintainer-handbooks.rst
* Cross-Architecture Development: Documentation/arch/index.rst
* Kernel Debugging: Documentation/process/debugging/kgdb.rst

Signature · 2 lines
Thanks,
Sasha
#8 lore raw

Re: [PATCH v2 1/2] README: restructure with role-based documentation and guidelines

In reply to Sasha Levin
Quoted 4 lines · Sasha Levin

Reorganize README to provide targeted documentation paths for different user roles including developers, researchers, security experts, maintainers, and AI coding assistants. Add quick start section and essential docs links.

This looks really great; thank you for writing it all out!

README line 170

Quoted 5 lines
README +5 -0
+* Attribution: Agents MUST add Assisted-by tag:
+  Assisted-by: $AGENT_NAME-$AGENT_MODEL-$AGENT_VERSION $TOOL1 $TOOL2 ...
+  Examples:
+  - Assisted-by: Claude-claude-3-opus-20240229 checkpatch git-bisect
+  - Assisted-by: GitHub-Copilot-GPT-4-v1.0.0 coccinelle sparse

I think "git" and "checkpatch" getting called out in Assisted-by is overkill/redundant. Devs are going to use git constantly, and checkpatch is already explicitly called out as a minimum standard linter for submitting patches.

As for agent formatting, it's hard to parse "-" separators if they're already used within the model/version. How about : or ; ?

--
Kees Cook

#9 lore raw

PATCH v2 2/2 agents: add unified agent coding assistant configuration

In reply to Sasha Levin

Create a single source of truth for agent instructions with symlinks for all major coding agents:
- CLAUDE.md (Claude Code)
- .github/copilot-instructions.md (GitHub Copilot)
- .cursorrules (Cursor)
- .codeium/instructions.md (Codeium)
- .continue/context.md (Continue)
- .windsurfrules (Windsurf)
- GEMINI.md (Gemini)

---
 .codeium/instructions.md        |  1 +
 .continue/context.md            |  1 +
 .cursorrules                    |  1 +
 .github/copilot-instructions.md |  1 +
 .gitignore                      | 10 ++++++++++
 .windsurfrules                  |  1 +
 CLAUDE.md                       |  1 +
 GEMINI.md                       |  1 +
 8 files changed, 17 insertions(+)
 create mode 100644 .codeium/instructions.md
 create mode 100644 .continue/context.md
 create mode 100644 .cursorrules
 create mode 100644 .github/copilot-instructions.md
 create mode 100644 .windsurfrules
 create mode 100644 CLAUDE.md
 create mode 100644 GEMINI.md
.codeium/instructions.md new file +1 -0
new file mode 100644
index 000000000000..8b6a7196d2b0
@@ -0,0 +1 @@
+@README
.continue/context.md new file +1 -0
new file mode 100644
index 000000000000..8b6a7196d2b0
@@ -0,0 +1 @@
+@README
.cursorrules new file +1 -0
new file mode 100644
index 000000000000..8b6a7196d2b0
@@ -0,0 +1 @@
+@README
.github/copilot-instructions.md new file +1 -0
new file mode 100644
index 000000000000..8b6a7196d2b0
@@ -0,0 +1 @@
+@README
.gitignore +10 -0
index bf5ee6e01cd4..f8f575ab8cf6 100644
@@ -182,3 +182,13 @@ sphinx_*/
 
 # Rust analyzer configuration
 /rust-project.json
+
+# Agentic coding assistant configuration
+.aider.conf.yml
+.codeium/
+.continue/
+.cursorrules
+.github/copilot-instructions.md
+.windsurfrules
+CLAUDE.md
+GEMINI.md
.windsurfrules new file +1 -0
new file mode 100644
index 000000000000..8b6a7196d2b0
@@ -0,0 +1 @@
+@README
CLAUDE.md new file +1 -0
new file mode 100644
index 000000000000..8b6a7196d2b0
@@ -0,0 +1 @@
+@README
GEMINI.md new file +1 -0
new file mode 100644
index 000000000000..8b6a7196d2b0
@@ -0,0 +1 @@
+@README
Signature · 1 line
2.39.5
#10 lore raw

Re: [PATCH v2 2/2] agents: add unified agent coding assistant configuration

Quoted 9 lines · Sasha Levin

Create a single source of truth for agent instructions with symlinks for all major coding agents:
- CLAUDE.md (Claude Code)
- .github/copilot-instructions.md (GitHub Copilot)
- .cursorrules (Cursor)
- .codeium/instructions.md (Codeium)
- .continue/context.md (Continue)
- .windsurfrules (Windsurf)
- GEMINI.md (Gemini)

Having these non-dot-files in the root directory for just specific closed source tools feels a bit wrong to me. I thought all of these tools were standardizing on "use README" and didn't need these extra helpers? The fact that most of them just contain README seems like that's the case, they just need to work it out somehow?

Anyway, I'd not like this patch to be added (patch 1/2 is great), as it feels like these agents need to get their act together in ways to not need these, we shouldn't be forced to deal with their inefficiencies.

thanks,

greg k-h

#11 lore raw

Re: [PATCH v2 2/2] agents: add unified agent coding assistant configuration

Quoted 17 lines · Greg KH
Quoted 9 lines · Sasha Levin

Create a single source of truth for agent instructions with symlinks for all major coding agents:
- CLAUDE.md (Claude Code)
- .github/copilot-instructions.md (GitHub Copilot)
- .cursorrules (Cursor)
- .codeium/instructions.md (Codeium)
- .continue/context.md (Continue)
- .windsurfrules (Windsurf)
- GEMINI.md (Gemini)

Having these non-dot-files in the root directory for just specific closed source tools feels a bit wrong to me. I thought all of these tools were standardizing on "use README" and didn't need these extra helpers? The fact that most of them just contain README seems like that's the case, they just need to work it out somehow?

Quoted 3 lines

Anyway, I'd not like this patch to be added (patch 1/2 is great), as it feels like these agents need to get their act together in ways to not need these, we shouldn't be forced to deal with their inefficiencies.

No, agents will not read the README unless we explicitly tell them to "study" the codebase (either via something like "/init" in the CLI tools or a "Scan the codebase" button on the VSCode clones).

This is why the agent files only have a reference to README: their only purpose is to get the agents to read the goddamn README file by default.

We don't strictly need this patch. Here are the options I came up with:

1. Multiple agent files: agents automatically read our rules, higher chance of comlpiance, doesn't require user to do anything manually.

2. No agents files at all: this means that the user will need to explicitly trigger an action, otherwise all the tools I've tested it with will happily ignore the README file even when prompted to do other actions on the codebase (analyze code/write a patch/etc).

3. Only "AGENTS.md" which seems like a few of the tools are trying to standardize on. We could also use it in the future to add prompt cues that might not be relevant within the README.

We could also start with most of these files, along with a statement that they will be removed within 12 months to give the various tools time to standardize around something.

Signature · 2 lines
Thanks,
Sasha
#12 lore raw

Re: [PATCH v2 2/2] agents: add unified agent coding assistant configuration

Quoted 5 lines · On Sun, 10 Aug 2025 10:22:15 -0400 Sasha Levin <[email protected]> wrote:

We don't strictly need this patch. Here are the options I came up with:

1. Multiple agent files: agents automatically read our rules, higher chance of comlpiance, doesn't require user to do anything manually.

Quoted 8 lines

2. No agents files at all: this means that the user will need to explicitly trigger an action, otherwise all the tools I've tested it with will happily ignore the README file even when prompted to do other actions on the codebase (analyze code/write a patch/etc).

3. Only "AGENTS.md" which seems like a few of the tools are trying to standardize on. We could also use it in the future to add prompt cues that might not be relevant within the README.

2 or 3 are the only options that seems reasonable. I agree with Greg. I wouldn't want these files adding noise to the main directory for every agent.

Quoted 4 lines

We could also start with most of these files, along with a statement that they will be removed within 12 months to give the various tools time to standardize around something.

Ideally, in 12 months they will all standardize on AGENTS.md and that's all we will need. Let's not enable them to do their own thing in the mean time. If we add this file, I would suspect it would help encourage the agents to use it.

The best "standards" are the ones that are done in collaboration before they are added to a specification ;-)

-- Steve

#13 lore raw

Re: [PATCH v2 2/2] agents: add unified agent coding assistant configuration

In reply to Sasha Levin
Quoted 11 lines · Sasha Levin

Create a single source of truth for agent instructions with symlinks for all major coding agents:
- CLAUDE.md (Claude Code)
- .github/copilot-instructions.md (GitHub Copilot)
- .cursorrules (Cursor)
- .codeium/instructions.md (Codeium)
- .continue/context.md (Continue)
- .windsurfrules (Windsurf)
- GEMINI.md (Gemini)

Still a big NAK from me for this for at least CLAUDE.md and GEMINI.md. I don't know about the other agents, but at least these two belong in .gitignore because they are files used for _personalized_ project management of the agent by the developer. Both Agents will find README automatically.

Please, just add to .gitignore:

CLAUDE.md
.claude/

etc...

This is exactly the same reason that debian/ is listed in .gitignore.

--
Kees Cook