diff --git a/cmd/bd/doctor/claude.go b/cmd/bd/doctor/claude.go
index d233ba9f..4715eb89 100644
--- a/cmd/bd/doctor/claude.go
+++ b/cmd/bd/doctor/claude.go
@@ -296,11 +296,15 @@ func CheckBdInPath() DoctorCheck {
 // CheckDocumentationBdPrimeReference checks if AGENTS.md or CLAUDE.md reference 'bd prime'
 // and verifies the command exists. This helps catch version mismatches where docs
 // reference features not available in the installed version.
+// Also supports local-only variants (claude.local.md) that are gitignored.
 func CheckDocumentationBdPrimeReference(repoPath string) DoctorCheck {
 	docFiles := []string{
 		filepath.Join(repoPath, "AGENTS.md"),
 		filepath.Join(repoPath, "CLAUDE.md"),
 		filepath.Join(repoPath, ".claude", "CLAUDE.md"),
+		// Local-only variants (not committed to repo)
+		filepath.Join(repoPath, "claude.local.md"),
+		filepath.Join(repoPath, ".claude", "claude.local.md"),
 	}
 
 	var filesWithBdPrime []string
diff --git a/cmd/bd/doctor/claude_test.go b/cmd/bd/doctor/claude_test.go
index 203169a0..203f782c 100644
--- a/cmd/bd/doctor/claude_test.go
+++ b/cmd/bd/doctor/claude_test.go
@@ -72,6 +72,22 @@ func TestCheckDocumentationBdPrimeReference(t *testing.T) {
 			expectedStatus: "ok",
 			expectDetail:   true,
 		},
+		{
+			name: "claude.local.md references bd prime (local-only)",
+			fileContent: map[string]string{
+				"claude.local.md": "Run bd prime for context.",
+			},
+			expectedStatus: "ok",
+			expectDetail:   true,
+		},
+		{
+			name: ".claude/claude.local.md references bd prime (local-only)",
+			fileContent: map[string]string{
+				".claude/claude.local.md": "Use bd prime for workflow context.",
+			},
+			expectedStatus: "ok",
+			expectDetail:   true,
+		},
 		{
 			name: "multiple files reference bd prime",
 			fileContent: map[string]string{
diff --git a/cmd/bd/doctor/legacy.go b/cmd/bd/doctor/legacy.go
index 47bff145..a7dde311 100644
--- a/cmd/bd/doctor/legacy.go
+++ b/cmd/bd/doctor/legacy.go
@@ -22,6 +22,9 @@ func CheckLegacyBeadsSlashCommands(repoPath string) DoctorCheck {
 		filepath.Join(repoPath, "AGENTS.md"),
 		filepath.Join(repoPath, "CLAUDE.md"),
 		filepath.Join(repoPath, ".claude", "CLAUDE.md"),
+		// Local-only variants (not committed to repo)
+		filepath.Join(repoPath, "claude.local.md"),
+		filepath.Join(repoPath, ".claude", "claude.local.md"),
 	}
 
 	var filesWithLegacyCommands []string
@@ -71,11 +74,15 @@ func CheckLegacyBeadsSlashCommands(repoPath string) DoctorCheck {
 
 // CheckAgentDocumentation checks if agent documentation (AGENTS.md or CLAUDE.md) exists
 // and recommends adding it if missing, suggesting bd onboard or bd setup claude.
+// Also supports local-only variants (claude.local.md) that are gitignored.
 func CheckAgentDocumentation(repoPath string) DoctorCheck {
 	docFiles := []string{
 		filepath.Join(repoPath, "AGENTS.md"),
 		filepath.Join(repoPath, "CLAUDE.md"),
 		filepath.Join(repoPath, ".claude", "CLAUDE.md"),
+		// Local-only variants (not committed to repo)
+		filepath.Join(repoPath, "claude.local.md"),
+		filepath.Join(repoPath, ".claude", "claude.local.md"),
 	}
 
 	var foundDocs []string
@@ -103,6 +110,10 @@ func CheckAgentDocumentation(repoPath string) DoctorCheck {
 			"  • Run 'bd onboard' to create AGENTS.md with workflow guidance\n" +
 			"  • Or run 'bd setup claude' to add Claude-specific documentation\n" +
 			"\n" +
+			"For local-only documentation (not committed to repo):\n" +
+			"  • Create claude.local.md or .claude/claude.local.md\n" +
+			"  • Add 'claude.local.md' to your .gitignore\n" +
+			"\n" +
 			"Recommended: Include bd workflow in your project documentation so\n" +
 			"AI agents understand how to track issues and manage dependencies",
 	}
diff --git a/cmd/bd/doctor/legacy_test.go b/cmd/bd/doctor/legacy_test.go
index 72a3b2a5..bcd0bafd 100644
--- a/cmd/bd/doctor/legacy_test.go
+++ b/cmd/bd/doctor/legacy_test.go
@@ -39,6 +39,18 @@ func TestCheckAgentDocumentation(t *testing.T) {
 			expectedStatus: "ok",
 			expectFix:      false,
 		},
+		{
+			name:           "claude.local.md exists (local-only)",
+			files:          []string{"claude.local.md"},
+			expectedStatus: "ok",
+			expectFix:      false,
+		},
+		{
+			name:           ".claude/claude.local.md exists (local-only)",
+			files:          []string{".claude/claude.local.md"},
+			expectedStatus: "ok",
+			expectFix:      false,
+		},
 		{
 			name:           "multiple docs",
 			files:          []string{"AGENTS.md", "CLAUDE.md"},
@@ -127,6 +139,22 @@ func TestCheckLegacyBeadsSlashCommands(t *testing.T) {
 			expectedStatus: "warning",
 			expectWarning:  true,
 		},
+		{
+			name: "legacy slash command in claude.local.md",
+			fileContent: map[string]string{
+				"claude.local.md": "Use /beads:show to see an issue.",
+			},
+			expectedStatus: "warning",
+			expectWarning:  true,
+		},
+		{
+			name: "legacy slash command in .claude/claude.local.md",
+			fileContent: map[string]string{
+				".claude/claude.local.md": "Use /beads:ready to see ready issues.",
+			},
+			expectedStatus: "warning",
+			expectWarning:  true,
+		},
 		{
 			name: "multiple files with legacy commands",
 			fileContent: map[string]string{