From 3cb0265ae7d0b42fbb6140b704b1fc952eda31af Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 11 Mar 2026 16:05:11 +0000
Subject: [PATCH] =?UTF-8?q?Add=20AGENTS.md=20=E2=86=92=20CLAUDE.md=20symli?=
 =?UTF-8?q?nk=20rule=20and=20create=20symlinks=20for=20existing=20files?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude Code reads CLAUDE.md for project context but ignores AGENTS.md.
To ensure Claude picks up job context wherever AGENTS.md files exist:

- Add `agents_md_claude_md_symlink` review rule to .deepreview that checks
  every AGENTS.md has a sibling CLAUDE.md symlink pointing to it
- Create CLAUDE.md symlinks for all 5 existing AGENTS.md files in the repo
- Update make_new_job.sh to create a CLAUDE.md symlink alongside AGENTS.md
  whenever a new job directory is scaffolded

https://claude.ai/code/session_013LSePqqcsCg1d6now3qseB
---
 .deepreview                                   | 24 +++++++++++++++++++
 .deepwork/jobs/test_job_flow/CLAUDE.md        |  1 +
 .deepwork/jobs/update_job_schema/CLAUDE.md    |  1 +
 CLAUDE.md                                     |  1 +
 doc/debugging_history/CLAUDE.md               |  1 +
 .../standard_jobs/deepwork_jobs/CLAUDE.md     |  1 +
 .../deepwork_jobs/make_new_job.sh             |  5 ++++
 7 files changed, 34 insertions(+)
 create mode 120000 .deepwork/jobs/test_job_flow/CLAUDE.md
 create mode 120000 .deepwork/jobs/update_job_schema/CLAUDE.md
 create mode 120000 CLAUDE.md
 create mode 120000 doc/debugging_history/CLAUDE.md
 create mode 120000 src/deepwork/standard_jobs/deepwork_jobs/CLAUDE.md

diff --git a/.deepreview b/.deepreview
index 1b599602..5ae763a6 100644
--- a/.deepreview
+++ b/.deepreview
@@ -470,6 +470,30 @@ job_schema_instruction_compatibility:
       - FAIL: Incompatibilities found. List each with the file path, line
         reference, the incompatible content, and what the schema actually says.
 
+agents_md_claude_md_symlink:
+  description: "Ensure every AGENTS.md file has a sibling CLAUDE.md symlink pointing to it, because Claude Code reads CLAUDE.md but ignores AGENTS.md."
+  match:
+    include:
+      - "**/AGENTS.md"
+  review:
+    strategy: individual
+    instructions: |
+      Claude Code reads CLAUDE.md for project context but does not read AGENTS.md.
+      Every AGENTS.md file MUST have a sibling CLAUDE.md that is a symlink pointing
+      to AGENTS.md, so that Claude Code picks up the same content.
+
+      Check whether a CLAUDE.md symlink exists in the same directory as the matched
+      AGENTS.md file. If it is missing or is not a symlink to AGENTS.md, create it:
+
+        ln -sf AGENTS.md <dir>/CLAUDE.md
+
+      The symlink target MUST be the relative path "AGENTS.md" (not an absolute path),
+      so the link remains valid after the directory is moved or cloned.
+
+      Output Format:
+      - PASS: CLAUDE.md symlink exists and points to AGENTS.md.
+      - FAIL: Symlink missing or incorrect — describe the current state and the fix applied.
+
 nix_claude_wrapper:
   description: "Ensure flake.nix always wraps the claude command with the required plugin dirs."
   match:
diff --git a/.deepwork/jobs/test_job_flow/CLAUDE.md b/.deepwork/jobs/test_job_flow/CLAUDE.md
new file mode 120000
index 00000000..47dc3e3d
--- /dev/null
+++ b/.deepwork/jobs/test_job_flow/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/.deepwork/jobs/update_job_schema/CLAUDE.md b/.deepwork/jobs/update_job_schema/CLAUDE.md
new file mode 120000
index 00000000..47dc3e3d
--- /dev/null
+++ b/.deepwork/jobs/update_job_schema/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 00000000..47dc3e3d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/doc/debugging_history/CLAUDE.md b/doc/debugging_history/CLAUDE.md
new file mode 120000
index 00000000..47dc3e3d
--- /dev/null
+++ b/doc/debugging_history/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/src/deepwork/standard_jobs/deepwork_jobs/CLAUDE.md b/src/deepwork/standard_jobs/deepwork_jobs/CLAUDE.md
new file mode 120000
index 00000000..47dc3e3d
--- /dev/null
+++ b/src/deepwork/standard_jobs/deepwork_jobs/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/src/deepwork/standard_jobs/deepwork_jobs/make_new_job.sh b/src/deepwork/standard_jobs/deepwork_jobs/make_new_job.sh
index 2ffa836a..45aec33f 100755
--- a/src/deepwork/standard_jobs/deepwork_jobs/make_new_job.sh
+++ b/src/deepwork/standard_jobs/deepwork_jobs/make_new_job.sh
@@ -128,6 +128,10 @@ This folder and its subfolders are managed using `deepwork_jobs` workflows.
 2. **Direct edits** are fine for minor instruction tweaks
 EOF
 
+    # Create CLAUDE.md symlink pointing to AGENTS.md so Claude Code picks up the context
+    # (Claude Code reads CLAUDE.md but ignores AGENTS.md)
+    ln -s AGENTS.md "$job_path/CLAUDE.md"
+
     # Copy .deepreview template if available
     if [[ -f "$script_dir/template.deepreview" ]]; then
         cp "$script_dir/template.deepreview" "$job_path/.deepreview"
@@ -139,6 +143,7 @@ EOF
         echo "  ├── .deepreview"
     fi
     echo "  ├── AGENTS.md"
+    echo "  ├── CLAUDE.md -> AGENTS.md"
     echo "  ├── steps/"
     echo "  ├── hooks/.gitkeep"
     echo "  ├── scripts/.gitkeep"