diff --git a/apps/mobile/src/app/(app)/(tabs)/(3_profile)/code-reviewer/[scope]/[platform]/(edit)/instructions.tsx b/apps/mobile/src/app/(app)/(tabs)/(3_profile)/code-reviewer/[scope]/[platform]/(edit)/instructions.tsx
index 63a5f82bd8..0f5d345b8c 100644
--- a/apps/mobile/src/app/(app)/(tabs)/(3_profile)/code-reviewer/[scope]/[platform]/(edit)/instructions.tsx
+++ b/apps/mobile/src/app/(app)/(tabs)/(3_profile)/code-reviewer/[scope]/[platform]/(edit)/instructions.tsx
@@ -26,6 +26,10 @@ function InstructionsEditor({
 
   return (
     <Animated.View entering={FadeIn.duration(200)} className="gap-4">
+      <Text className="text-sm text-muted-foreground">
+        Custom Instructions is planned for deprecation. Move these guidelines into a REVIEW.md file
+        in your repository instead.
+      </Text>
       <TextInput
         className="h-32 rounded-lg bg-secondary p-3 text-sm leading-5 text-foreground"
         multiline
diff --git a/apps/mobile/src/components/code-reviewer/platform-overview-rows.ts b/apps/mobile/src/components/code-reviewer/platform-overview-rows.ts
index 348fb29556..e8034e92a9 100644
--- a/apps/mobile/src/components/code-reviewer/platform-overview-rows.ts
+++ b/apps/mobile/src/components/code-reviewer/platform-overview-rows.ts
@@ -52,12 +52,18 @@ export function buildOverviewRows({
       subtitle:
         data.focusAreas.length > 0 ? data.focusAreas.map(capitalize).join(', ') : 'All areas',
     },
-    {
-      field: 'instructions',
-      icon: ScrollText,
-      title: 'Custom Instructions',
-      subtitle: data.customInstructions ? 'Set' : 'None',
-    },
+    // Custom Instructions is deprecated in favour of REVIEW.md, so the row is
+    // only offered to configs that already have something stored in it.
+    ...(data.customInstructions?.trim()
+      ? [
+          {
+            field: 'instructions',
+            icon: ScrollText,
+            title: 'Custom Instructions',
+            subtitle: 'Set',
+          },
+        ]
+      : []),
     {
       field: 'model',
       icon: FileSliders,
diff --git a/apps/web/src/components/code-reviews/BitbucketReviewConfigForm.tsx b/apps/web/src/components/code-reviews/BitbucketReviewConfigForm.tsx
index 2d867822be..e26a3368cc 100644
--- a/apps/web/src/components/code-reviews/BitbucketReviewConfigForm.tsx
+++ b/apps/web/src/components/code-reviews/BitbucketReviewConfigForm.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import { useEffect, useMemo, useState } from 'react';
+import Link from 'next/link';
 import { formatDistanceToNow } from 'date-fns';
 import { AlertCircle, Play, RefreshCw, Save, Settings2, ShieldCheck } from 'lucide-react';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
@@ -84,9 +85,16 @@ export function BitbucketReviewConfigForm({ organizationId }: BitbucketReviewCon
   const [mutationError, setMutationError] = useState<string | null>(null);
   const [manualReviewUrl, setManualReviewUrl] = useState('');
   const [manualReviewError, setManualReviewError] = useState<string | null>(null);
+  // Custom instructions is deprecated in favour of REVIEW.md. The field is only
+  // surfaced to configs that already have something stored in it, and stays
+  // visible for the rest of the session even if the user clears it.
+  const [showCustomInstructions, setShowCustomInstructions] = useState(false);
 
   useEffect(() => {
     if (!configQuery.data) return;
+    if (configQuery.data.customInstructions?.trim()) {
+      setShowCustomInstructions(true);
+    }
     const nextConfig: BitbucketReviewConfig = {
       reviewStyle: configQuery.data.reviewStyle,
       focusAreas: configQuery.data.focusAreas,
@@ -530,19 +538,34 @@ export function BitbucketReviewConfigForm({ organizationId }: BitbucketReviewCon
               </div>
             </div>
 
-            <div className="space-y-2 border-t border-border pt-6">
-              <Label htmlFor="bitbucket-custom-instructions">Custom instructions (optional)</Label>
-              <Textarea
-                id="bitbucket-custom-instructions"
-                value={draft.customInstructions}
-                onChange={event =>
-                  setDraft(current => ({ ...current, customInstructions: event.target.value }))
-                }
-                placeholder="Add repository-specific review guidance for your team."
-                rows={4}
-                className="resize-none"
-              />
-            </div>
+            {/* Deprecated — only shown to configs that already have custom instructions stored. */}
+            {showCustomInstructions && (
+              <div className="space-y-2 border-t border-border pt-6">
+                <Label htmlFor="bitbucket-custom-instructions">
+                  Custom instructions (optional)
+                </Label>
+                <Textarea
+                  id="bitbucket-custom-instructions"
+                  value={draft.customInstructions}
+                  onChange={event =>
+                    setDraft(current => ({ ...current, customInstructions: event.target.value }))
+                  }
+                  placeholder="Add repository-specific review guidance for your team."
+                  rows={4}
+                  className="resize-none"
+                />
+                <p className="text-muted-foreground text-sm">
+                  Custom Instructions is planned for deprecation. Move these guidelines into a
+                  REVIEW.md file in your repository instead.{' '}
+                  <Link
+                    href={`/organizations/${organizationId}/code-reviews/review-md`}
+                    className="text-blue-400 underline-offset-2 hover:text-blue-300 hover:underline"
+                  >
+                    Learn about REVIEW.md
+                  </Link>
+                </p>
+              </div>
+            )}
           </div>
 
           <div className="flex flex-col gap-3 border-t border-border pt-6 sm:flex-row sm:items-center sm:justify-between">
diff --git a/apps/web/src/components/code-reviews/ReviewConfigForm.tsx b/apps/web/src/components/code-reviews/ReviewConfigForm.tsx
index 36ea5b2d18..73fe67d2f3 100644
--- a/apps/web/src/components/code-reviews/ReviewConfigForm.tsx
+++ b/apps/web/src/components/code-reviews/ReviewConfigForm.tsx
@@ -245,6 +245,10 @@ export function ReviewConfigForm({
   );
   const [focusAreas, setFocusAreas] = useState<string[]>([]);
   const [customInstructions, setCustomInstructions] = useState('');
+  // Custom Instructions is deprecated in favour of REVIEW.md. The field is only
+  // surfaced to configs that already have something stored in it, and stays
+  // visible for the rest of the session even if the user clears it.
+  const [showCustomInstructions, setShowCustomInstructions] = useState(false);
   const [selectedModel, setSelectedModel] = useState(PRIMARY_DEFAULT_MODEL);
   const [thinkingEffort, setThinkingEffort] = useState<string | null>(null);
   const [gateThreshold, setGateThreshold] = useState<'off' | 'all' | 'warning' | 'critical'>('off');
@@ -372,6 +376,9 @@ export function ReviewConfigForm({
       setReviewStyle(configData.reviewStyle);
       setFocusAreas(configData.focusAreas);
       setCustomInstructions(configData.customInstructions || '');
+      if (configData.customInstructions?.trim()) {
+        setShowCustomInstructions(true);
+      }
       setSelectedModel(configData.modelSlug);
       setThinkingEffort(configData.thinkingEffort ?? null);
       setGateThreshold(configData.gateThreshold ?? 'off');
@@ -867,21 +874,30 @@ export function ReviewConfigForm({
               </div>
             </div>
 
-            {/* Custom Instructions (global) */}
-            <div className="space-y-3">
-              <Label htmlFor="custom-instructions">Custom Instructions (Optional)</Label>
-              <Textarea
-                id="custom-instructions"
-                placeholder="e.g., 'Always check for TypeScript strict mode compliance' or 'Focus on React best practices'"
-                value={customInstructions}
-                onChange={e => setCustomInstructions(e.target.value)}
-                rows={4}
-                className="resize-none"
-              />
-              <p className="text-muted-foreground text-sm">
-                Add specific guidelines for your team's code review standards
-              </p>
-            </div>
+            {/* Custom Instructions (global) — deprecated, only shown to configs that already use it */}
+            {showCustomInstructions && (
+              <div className="space-y-3">
+                <Label htmlFor="custom-instructions">Custom Instructions (Optional)</Label>
+                <Textarea
+                  id="custom-instructions"
+                  placeholder="e.g., 'Always check for TypeScript strict mode compliance' or 'Focus on React best practices'"
+                  value={customInstructions}
+                  onChange={e => setCustomInstructions(e.target.value)}
+                  rows={4}
+                  className="resize-none"
+                />
+                <p className="text-muted-foreground text-sm">
+                  Custom Instructions is planned for deprecation. Move these guidelines into a
+                  REVIEW.md file in your repository instead.{' '}
+                  <Link
+                    href={reviewMdGuideHref}
+                    className="text-blue-400 underline-offset-2 hover:text-blue-300 hover:underline"
+                  >
+                    Learn about REVIEW.md
+                  </Link>
+                </p>
+              </div>
+            )}
 
             {/* Advanced Settings — one card holding the switch and, when on, the per-repository
                 settings. GitLab has no "all" mode, so it is always Advanced (switch hidden). */}