Create a single source of truth for AI instructions in
Documentation/AI/main.md with symlinks for all major AI coding
assistants:
- CLAUDE.md (Claude Code)
- .github/copilot-instructions.md (GitHub Copilot)
- .cursorrules (Cursor)
- .codeium/instructions.md (Codeium)
- .continue/context.md (Continue)
- .windsurfrules (Windsurf)
- Documentation/AIder.conf.yml (Aider)
Signed-off-by: Sasha Levin <sashal@kernel.org>
---
.aider.conf.yml | 1 +
.codeium/instructions.md | 1 +
.continue/context.md | 1 +
.cursorrules | 1 +
.github/copilot-instructions.md | 1 +
.windsurfrules | 1 +
CLAUDE.md | 1 +
Documentation/AI/main.md | 5 +++++
8 files changed, 12 insertions(+)
create mode 120000 .aider.conf.yml
create mode 120000 .codeium/instructions.md
create mode 120000 .continue/context.md
create mode 120000 .cursorrules
create mode 120000 .github/copilot-instructions.md
create mode 120000 .windsurfrules
create mode 120000 CLAUDE.md
create mode 100644 Documentation/AI/main.md
diff --git a/.aider.conf.yml b/.aider.conf.yml
new file mode 120000
index 0000000000000..201abbf2af4de
--- /dev/null
+++ b/.aider.conf.yml
@@ -0,0 +1 @@
+Documentation/AI/main.md
\ No newline at end of file
diff --git a/.codeium/instructions.md b/.codeium/instructions.md
new file mode 120000
index 0000000000000..69274c2ad2f60
--- /dev/null
+++ b/.codeium/instructions.md
@@ -0,0 +1 @@
+../Documentation/AI/main.md
\ No newline at end of file
diff --git a/.continue/context.md b/.continue/context.md
new file mode 120000
index 0000000000000..69274c2ad2f60
--- /dev/null
+++ b/.continue/context.md
@@ -0,0 +1 @@
+../Documentation/AI/main.md
\ No newline at end of file
diff --git a/.cursorrules b/.cursorrules
new file mode 120000
index 0000000000000..201abbf2af4de
--- /dev/null
+++ b/.cursorrules
@@ -0,0 +1 @@
+Documentation/AI/main.md
\ No newline at end of file
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 120000
index 0000000000000..69274c2ad2f60
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1 @@
+../Documentation/AI/main.md
\ No newline at end of file
diff --git a/.windsurfrules b/.windsurfrules
new file mode 120000
index 0000000000000..201abbf2af4de
--- /dev/null
+++ b/.windsurfrules
@@ -0,0 +1 @@
+Documentation/AI/main.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000000000..201abbf2af4de
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+Documentation/AI/main.md
\ No newline at end of file
diff --git a/Documentation/AI/main.md b/Documentation/AI/main.md
new file mode 100644
index 0000000000000..959ba50568f57
--- /dev/null
+++ b/Documentation/AI/main.md
@@ -0,0 +1,5 @@
+# Linux Kernel Development AI Instructions
+
+This is the Linux kernel repository. When working with this codebase, you must follow the following rules:
+
+- [ TODO ]
--
2.39.5On Fri, Jul 25, 2025 at 01:53:57PM -0400, Sasha Levin wrote: > Create a single source of truth for AI instructions in > Documentation/AI/main.md with symlinks for all major AI coding > assistants: > - CLAUDE.md (Claude Code) > - .github/copilot-instructions.md (GitHub Copilot) > - .cursorrules (Cursor) > - .codeium/instructions.md (Codeium) > - .continue/context.md (Continue) > - .windsurfrules (Windsurf) > - Documentation/AIder.conf.yml (Aider) I do like the idea of having a standard baseline for agentic development, but: - This clobbers per-project information storage for the agents, which the dev may want to be adjusting locally. I would strongly prefer adding all of those files to .gitignore instead. - Documentation/ should not start getting filled with stuff to be exclusively consumed by agents. Instead, I recommend a top-level .md file that agents can discover that contains very simple non-specific prompts about what they can find in Documentation/, and drop a reference to the file in, say, Makefile to be discovered during the agent's scrape of the project. I'd recommend something very simple like: diff --git a/Makefile b/Makefile index e05bd43f93bd..998b037e6d4d 100644 --- a/Makefile +++ b/Makefile @@ -7,6 +7,7 @@ NAME = Baby Opossum Posse # *DOCUMENTATION* # To see a list of typical targets execute "make help" +# AI agents and LLMs should read ./AGENTS.md # More info can be located in ./README # Comments in this file are targeted only to the developer, do not # expect to learn how to build the kernel reading this file. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000000..3df98f0cc667 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,3 @@ +To work on the Linux kernel, please see Makefile for details on how to +perform builds and testing. Find and read the Submitting Patches and +Coding Style rules in Documentation/. Now if we wanted to write up a human-readable .rst file about the expectations of what we expect from Agents, let's do that, but I would like to focus on putting the burden of understanding on the Agents, not the humans. -Kees -- Kees Cook
On Fri, Jul 25, 2025 at 01:40:55PM -0700, Kees Cook wrote: >On Fri, Jul 25, 2025 at 01:53:57PM -0400, Sasha Levin wrote: >> Create a single source of truth for AI instructions in >> Documentation/AI/main.md with symlinks for all major AI coding >> assistants: >> - CLAUDE.md (Claude Code) >> - .github/copilot-instructions.md (GitHub Copilot) >> - .cursorrules (Cursor) >> - .codeium/instructions.md (Codeium) >> - .continue/context.md (Continue) >> - .windsurfrules (Windsurf) >> - Documentation/AIder.conf.yml (Aider) > >I do like the idea of having a standard baseline for agentic >development, but: > >- This clobbers per-project information storage for the agents, which > the dev may want to be adjusting locally. I would strongly prefer > adding all of those files to .gitignore instead. It will, but: 1. We don't have a different place to write this down (more below). 2. Users have other places they can add their specific instructions, or they can even carry patches on top. >- Documentation/ should not start getting filled with stuff to be > exclusively consumed by agents. Instead, I recommend a top-level > .md file that agents can discover that contains very simple > non-specific prompts about what they can find in Documentation/, > and drop a reference to the file in, say, Makefile to be discovered > during the agent's scrape of the project. > >I'd recommend something very simple like: > >diff --git a/Makefile b/Makefile >index e05bd43f93bd..998b037e6d4d 100644 >--- a/Makefile >+++ b/Makefile >@@ -7,6 +7,7 @@ NAME = Baby Opossum Posse > > # *DOCUMENTATION* > # To see a list of typical targets execute "make help" >+# AI agents and LLMs should read ./AGENTS.md > # More info can be located in ./README > # Comments in this file are targeted only to the developer, do not > # expect to learn how to build the kernel reading this file. >diff --git a/AGENTS.md b/AGENTS.md >new file mode 100644 >index 000000000000..3df98f0cc667 >--- /dev/null >+++ b/AGENTS.md >@@ -0,0 +1,3 @@ >+To work on the Linux kernel, please see Makefile for details on how to >+perform builds and testing. Find and read the Submitting Patches and >+Coding Style rules in Documentation/. I've removed CLAUDE.md, and applied the following change on top of this RFC patchset with Claude: diff --git a/Makefile b/Makefile index be33e8c868ae2..e3986eae88e08 100644 --- a/Makefile +++ b/Makefile @@ -7,6 +7,7 @@ NAME = Baby Opossum Posse # *DOCUMENTATION* # To see a list of typical targets execute "make help" +# AI agents and LLMs should read ./Documentation/AI/main.md # More info can be located in ./README # Comments in this file are targeted only to the developer, do not # expect to learn how to build the kernel reading this file. ... which Claude (and I suspect most other other agents) proceeds to ignore as it doesn't really do any scraping outside of those dedicated files: $ claude -p "do you need to attribute your commits?" No, I don't need to attribute commits myself. When creating commits, I follow the format specified in my instructions: ``` 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> ``` This attribution is automatically added to commit messages when I create commits for you -- Thanks, Sasha
Sasha Levin <sashal@kernel.org> writes: > Create a single source of truth for AI instructions in > Documentation/AI/main.md with symlinks for all major AI coding > assistants: > - CLAUDE.md (Claude Code) > - .github/copilot-instructions.md (GitHub Copilot) > - .cursorrules (Cursor) > - .codeium/instructions.md (Codeium) > - .continue/context.md (Continue) > - .windsurfrules (Windsurf) > - Documentation/AIder.conf.yml (Aider) > > Signed-off-by: Sasha Levin <sashal@kernel.org> > --- > .aider.conf.yml | 1 + > .codeium/instructions.md | 1 + > .continue/context.md | 1 + > .cursorrules | 1 + > .github/copilot-instructions.md | 1 + > .windsurfrules | 1 + > CLAUDE.md | 1 + > Documentation/AI/main.md | 5 +++++ So I'm gonna ignore (for now) the substantive issues here to ask: do we *really* need to introduce Markdown into Documentation/? Are these things really unable to understand RST? Why not add a file that can be part of the docs build so people can see the instructions that are being provided? Thanks, jon
On Fri, Jul 25, 2025 at 12:27:50PM -0600, Jonathan Corbet wrote:
>Sasha Levin <sashal@kernel.org> writes:
>
>> Create a single source of truth for AI instructions in
>> Documentation/AI/main.md with symlinks for all major AI coding
>> assistants:
>> - CLAUDE.md (Claude Code)
>> - .github/copilot-instructions.md (GitHub Copilot)
>> - .cursorrules (Cursor)
>> - .codeium/instructions.md (Codeium)
>> - .continue/context.md (Continue)
>> - .windsurfrules (Windsurf)
>> - Documentation/AIder.conf.yml (Aider)
>>
>> Signed-off-by: Sasha Levin <sashal@kernel.org>
>> ---
>> .aider.conf.yml | 1 +
>> .codeium/instructions.md | 1 +
>> .continue/context.md | 1 +
>> .cursorrules | 1 +
>> .github/copilot-instructions.md | 1 +
>> .windsurfrules | 1 +
>> CLAUDE.md | 1 +
>> Documentation/AI/main.md | 5 +++++
>
>So I'm gonna ignore (for now) the substantive issues here to ask: do we
>*really* need to introduce Markdown into Documentation/? Are these
>things really unable to understand RST? Why not add a file that can be
>part of the docs build so people can see the instructions that are being
>provided?
From my understanding, most of the agents out there expect a markdown
file ("CLAUDE.md", ".github/copilot-instructions.md", etc).
All the documentation and examples I can find online insist on
markdown... I suspect that they will also understand RST, but then we'll
be doing something "unsupported".
Though in this scenario, maybe even just plain text will be enough?
--
Thanks,
Sasha
On Fri, Jul 25, 2025 at 06:15:33PM -0400, Sasha Levin wrote:
>On Fri, Jul 25, 2025 at 12:27:50PM -0600, Jonathan Corbet wrote:
>>Sasha Levin <sashal@kernel.org> writes:
>>
>>>Create a single source of truth for AI instructions in
>>>Documentation/AI/main.md with symlinks for all major AI coding
>>>assistants:
>>>- CLAUDE.md (Claude Code)
>>>- .github/copilot-instructions.md (GitHub Copilot)
>>>- .cursorrules (Cursor)
>>>- .codeium/instructions.md (Codeium)
>>>- .continue/context.md (Continue)
>>>- .windsurfrules (Windsurf)
>>>- Documentation/AIder.conf.yml (Aider)
>>>
>>>Signed-off-by: Sasha Levin <sashal@kernel.org>
>>>---
>>> .aider.conf.yml | 1 +
>>> .codeium/instructions.md | 1 +
>>> .continue/context.md | 1 +
>>> .cursorrules | 1 +
>>> .github/copilot-instructions.md | 1 +
>>> .windsurfrules | 1 +
>>> CLAUDE.md | 1 +
>>> Documentation/AI/main.md | 5 +++++
>>
>>So I'm gonna ignore (for now) the substantive issues here to ask: do we
>>*really* need to introduce Markdown into Documentation/? Are these
>>things really unable to understand RST? Why not add a file that can be
>>part of the docs build so people can see the instructions that are being
>>provided?
>
>From my understanding, most of the agents out there expect a markdown
>file ("CLAUDE.md", ".github/copilot-instructions.md", etc).
>
>All the documentation and examples I can find online insist on
>markdown... I suspect that they will also understand RST, but then we'll
>be doing something "unsupported".
>
>Though in this scenario, maybe even just plain text will be enough?
I've tested providing a RST file instead of markdown to Claude, Copilot,
and Cursor. All 3 seemed to be okay with it and followed the
instructions in it.
I'll switch to RST.
--
Thanks,
Sasha
Em Sat, 26 Jul 2025 22:24:08 -0400
Sasha Levin <sashal@kernel.org> escreveu:
> On Fri, Jul 25, 2025 at 06:15:33PM -0400, Sasha Levin wrote:
> >On Fri, Jul 25, 2025 at 12:27:50PM -0600, Jonathan Corbet wrote:
> >>Sasha Levin <sashal@kernel.org> writes:
> >>
> >>>Create a single source of truth for AI instructions in
> >>>Documentation/AI/main.md with symlinks for all major AI coding
> >>>assistants:
> >>>- CLAUDE.md (Claude Code)
> >>>- .github/copilot-instructions.md (GitHub Copilot)
> >>>- .cursorrules (Cursor)
> >>>- .codeium/instructions.md (Codeium)
> >>>- .continue/context.md (Continue)
> >>>- .windsurfrules (Windsurf)
> >>>- Documentation/AIder.conf.yml (Aider)
> >>>
> >>>Signed-off-by: Sasha Levin <sashal@kernel.org>
> >>>---
> >>> .aider.conf.yml | 1 +
> >>> .codeium/instructions.md | 1 +
> >>> .continue/context.md | 1 +
> >>> .cursorrules | 1 +
> >>> .github/copilot-instructions.md | 1 +
> >>> .windsurfrules | 1 +
> >>> CLAUDE.md | 1 +
> >>> Documentation/AI/main.md | 5 +++++
> >>
> >>So I'm gonna ignore (for now) the substantive issues here to ask: do we
> >>*really* need to introduce Markdown into Documentation/? Are these
> >>things really unable to understand RST? Why not add a file that can be
> >>part of the docs build so people can see the instructions that are being
> >>provided?
> >
> >From my understanding, most of the agents out there expect a markdown
> >file ("CLAUDE.md", ".github/copilot-instructions.md", etc).
> >
> >All the documentation and examples I can find online insist on
> >markdown... I suspect that they will also understand RST, but then we'll
> >be doing something "unsupported".
> >
> >Though in this scenario, maybe even just plain text will be enough?
>
> I've tested providing a RST file instead of markdown to Claude, Copilot,
> and Cursor. All 3 seemed to be okay with it and followed the
> instructions in it.
>
> I'll switch to RST.
Maybe you can also check if aren't there one "unified" file where
others would read, or if are there any efforts to unify them.
I strongly suspect that, if not now, with time, they'll all end
supporting "alien" files for the most popular tools, if they don't
find their own special file name.
Thanks,
Mauro
On Fri, 25 Jul 2025 13:53:57 -0400 Sasha Levin <sashal@kernel.org> wrote: > Create a single source of truth for AI instructions in > Documentation/AI/main.md with symlinks for all major AI coding > assistants: > - CLAUDE.md (Claude Code) > - .github/copilot-instructions.md (GitHub Copilot) > - .cursorrules (Cursor) > - .codeium/instructions.md (Codeium) > - .continue/context.md (Continue) > - .windsurfrules (Windsurf) > - Documentation/AIder.conf.yml (Aider) So these AI tools know to read these? -- Steve > > Signed-off-by: Sasha Levin <sashal@kernel.org>
On Fri, Jul 25, 2025 at 02:19:58PM -0400, Steven Rostedt wrote: >On Fri, 25 Jul 2025 13:53:57 -0400 >Sasha Levin <sashal@kernel.org> wrote: > >> Create a single source of truth for AI instructions in >> Documentation/AI/main.md with symlinks for all major AI coding >> assistants: >> - CLAUDE.md (Claude Code) >> - .github/copilot-instructions.md (GitHub Copilot) >> - .cursorrules (Cursor) >> - .codeium/instructions.md (Codeium) >> - .continue/context.md (Continue) >> - .windsurfrules (Windsurf) >> - Documentation/AIder.conf.yml (Aider) > >So these AI tools know to read these? Yup! These are the "magic" files agents try to read and add into their context as they start up. -- Thanks, Sasha
© 2016 - 2025 Red Hat, Inc.