From 1ecb403e798016d4e427c3289d20a1b32e21dbac Mon Sep 17 00:00:00 2001
From: "posthog[bot]" <206114724+posthog[bot]@users.noreply.github.com>
Date: Tue, 28 Jul 2026 20:37:24 +0000
Subject: [PATCH] feat(agent): Instruct agent to follow repo rules and match
 comment style

Adds a "Repository Conventions" block to the agent's appended system-prompt
instructions telling it to discover and follow repo-level convention files
(CLAUDE.md, AGENTS.md, .cursorrules, .cursor/rules/*.mdc) and to mirror the
existing code's comment density instead of adding narrating comments.

Claude Code loads CLAUDE.md/AGENTS.md natively but never reads Cursor rules,
and nothing previously reinforced matching the repo's comment style. This
addresses inbox-beta feedback that generated PRs ignore the user's coding
style, add unnecessary comments, and don't follow the repo's cursor/claude
rules.

Applies to every session (desktop and cloud, including inbox-generated PRs)
via buildAppendedInstructions -> buildSystemPrompt.

Generated-By: PostHog Code
Task-Id: 0a966bbb-531f-439e-a3c2-c2c6b0aabb79
---
 .../adapters/claude/session/instructions.test.ts |  7 +++++++
 .../src/adapters/claude/session/instructions.ts  | 16 +++++++++++++++-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/packages/agent/src/adapters/claude/session/instructions.test.ts b/packages/agent/src/adapters/claude/session/instructions.test.ts
index 0721a80f67..88679bcca2 100644
--- a/packages/agent/src/adapters/claude/session/instructions.test.ts
+++ b/packages/agent/src/adapters/claude/session/instructions.test.ts
@@ -20,4 +20,11 @@ describe("buildAppendedInstructions", () => {
     expect(withNarration.startsWith(withoutNarration)).toBe(true);
     expect(withoutNarration.length).toBeGreaterThan(0);
   });
+
+  it("tells the agent to follow repo conventions, including Cursor rules", () => {
+    const instructions = buildAppendedInstructions({ spokenNarration: false });
+    expect(instructions).toContain("# Repository Conventions");
+    expect(instructions).toContain(".cursor/rules/");
+    expect(instructions).toContain("comment density");
+  });
 });
diff --git a/packages/agent/src/adapters/claude/session/instructions.ts b/packages/agent/src/adapters/claude/session/instructions.ts
index 055cab7075..b8ebfdfbda 100644
--- a/packages/agent/src/adapters/claude/session/instructions.ts
+++ b/packages/agent/src/adapters/claude/session/instructions.ts
@@ -43,6 +43,15 @@ Optimize for the fewest shell round trips.
 - Never rerun a command solely to reproduce output you already have.
 `;
 
+const REPOSITORY_CONVENTIONS = `
+# Repository Conventions
+
+Make your changes read like the surrounding code so they pass review unchanged. Match the repository's own conventions rather than imposing your own defaults.
+
+- Before writing code, look for repo-level convention files and follow them: \`CLAUDE.md\`, \`AGENTS.md\`, \`.cursorrules\`, and any rule files under \`.cursor/rules/\` (usually \`*.mdc\`). You load \`CLAUDE.md\` and \`AGENTS.md\` automatically, but you do NOT read Cursor rules on your own — open and honor those files yourself whenever they are present.
+- Mirror the existing code's style: naming, formatting, imports, and especially comment density. Do NOT add comments that narrate your change or restate what the code plainly does. Only add a comment where the surrounding code already would, or where it explains genuinely non-obvious intent. Unnecessary comments read as noise and are a common review complaint.
+`;
+
 const SPOKEN_NARRATION = `
 # Spoken Narration
 
@@ -64,7 +73,12 @@ How to phrase the line:
 `;
 
 const BASE_INSTRUCTIONS =
-  BRANCH_NAMING + PULL_REQUEST_LINKS + PLAN_MODE + MCP_TOOLS + SHELL_EFFICIENCY;
+  BRANCH_NAMING +
+  PULL_REQUEST_LINKS +
+  PLAN_MODE +
+  MCP_TOOLS +
+  SHELL_EFFICIENCY +
+  REPOSITORY_CONVENTIONS;
 
 export function buildAppendedInstructions(opts: {
   spokenNarration: boolean;