refactor: enhance context file handling in AgentService and AutoModeService

- Updated both services to conditionally load context files while excluding CLAUDE.md when autoLoadClaudeMd is enabled, preventing duplication.
- Improved the structure and clarity of the context files prompt, emphasizing the importance of following project-specific rules and conventions.
- Ensured consistent handling of context file loading across different methods in both services.

apps/server/src/services/agent-service.ts

@@ -198,15 +198,53 @@ export class AgentService {
       );
 
       // Load project context files (CLAUDE.md, CODE_QUALITY.md, etc.)
-      // Note: When autoLoadClaudeMd is enabled, skip loading CLAUDE.md here since SDK handles it
+      const contextResult = await loadContextFiles({
-      // to avoid duplication. The SDK's settingSources will load CLAUDE.md from standard locations.
+        projectPath: effectiveWorkDir,
-      const { formattedPrompt: contextFilesPrompt } = autoLoadClaudeMd
+        fsModule: secureFs as Parameters<typeof loadContextFiles>[0]['fsModule'],
-        ? { formattedPrompt: '' }
+      });
-        : await loadContextFiles({
+
-            projectPath: effectiveWorkDir,
+      // When autoLoadClaudeMd is enabled, filter out CLAUDE.md to avoid duplication
-            fsModule: secureFs as Parameters<typeof loadContextFiles>[0]['fsModule'],
+      // (SDK handles CLAUDE.md via settingSources), but keep other context files like CODE_QUALITY.md
+      let contextFilesPrompt = contextResult.formattedPrompt;
+      if (autoLoadClaudeMd && contextResult.files.length > 0) {
+        const nonClaudeFiles = contextResult.files.filter(
+          (f) => f.name.toLowerCase() !== 'claude.md'
+        );
+
+        // Rebuild prompt without CLAUDE.md
+        if (nonClaudeFiles.length > 0) {
+          const formattedFiles = nonClaudeFiles.map((file) => {
+            const header = `## ${file.name}`;
+            const pathInfo = `**Path:** \`${file.path}\``;
+            const descriptionInfo = file.description ? `\n**Purpose:** ${file.description}` : '';
+            return `${header}\n${pathInfo}${descriptionInfo}\n\n${file.content}`;
           });
 
+          contextFilesPrompt = `# Project Context Files
+
+The following context files provide project-specific rules, conventions, and guidelines.
+Each file serves a specific purpose - use the description to understand when to reference it.
+If you need more details about a context file, you can read the full file at the path provided.
+
+**IMPORTANT**: You MUST follow the rules and conventions specified in these files.
+- Follow ALL commands exactly as shown (e.g., if the project uses \`pnpm\`, NEVER use \`npm\` or \`npx\`)
+- Follow ALL coding conventions, commit message formats, and architectural patterns specified
+- Reference these rules before running ANY shell commands or making commits
+
+---
+
+${formattedFiles.join('\n\n---\n\n')}
+
+---
+
+**REMINDER**: Before taking any action, verify you are following the conventions specified above.
+`;
+        } else {
+          // All files were CLAUDE.md, so no context to add
+          contextFilesPrompt = '';
+        }
+      }
+
       // Build combined system prompt with base prompt and context files
       const baseSystemPrompt = this.getSystemPrompt();
       const combinedSystemPrompt = contextFilesPrompt

apps/server/src/services/auto-mode-service.ts

@@ -569,15 +569,53 @@ export class AutoModeService {
       // Build the prompt - use continuation prompt if provided (for recovery after plan approval)
       let prompt: string;
       // Load project context files (CLAUDE.md, CODE_QUALITY.md, etc.) - passed as system prompt
-      // Note: When autoLoadClaudeMd is enabled, skip loading CLAUDE.md here since SDK handles it
+      const contextResult = await loadContextFiles({
-      // to avoid duplication. The SDK's settingSources will load CLAUDE.md from standard locations.
+        projectPath,
-      const { formattedPrompt: contextFilesPrompt } = autoLoadClaudeMd
+        fsModule: secureFs as Parameters<typeof loadContextFiles>[0]['fsModule'],
-        ? { formattedPrompt: '' }
+      });
-        : await loadContextFiles({
+
-            projectPath,
+      // When autoLoadClaudeMd is enabled, filter out CLAUDE.md to avoid duplication
-            fsModule: secureFs as Parameters<typeof loadContextFiles>[0]['fsModule'],
+      // (SDK handles CLAUDE.md via settingSources), but keep other context files like CODE_QUALITY.md
+      let contextFilesPrompt = contextResult.formattedPrompt;
+      if (autoLoadClaudeMd && contextResult.files.length > 0) {
+        const nonClaudeFiles = contextResult.files.filter(
+          (f) => f.name.toLowerCase() !== 'claude.md'
+        );
+
+        // Rebuild prompt without CLAUDE.md
+        if (nonClaudeFiles.length > 0) {
+          const formattedFiles = nonClaudeFiles.map((file) => {
+            const header = `## ${file.name}`;
+            const pathInfo = `**Path:** \`${file.path}\``;
+            const descriptionInfo = file.description ? `\n**Purpose:** ${file.description}` : '';
+            return `${header}\n${pathInfo}${descriptionInfo}\n\n${file.content}`;
           });
 
+          contextFilesPrompt = `# Project Context Files
+
+The following context files provide project-specific rules, conventions, and guidelines.
+Each file serves a specific purpose - use the description to understand when to reference it.
+If you need more details about a context file, you can read the full file at the path provided.
+
+**IMPORTANT**: You MUST follow the rules and conventions specified in these files.
+- Follow ALL commands exactly as shown (e.g., if the project uses \`pnpm\`, NEVER use \`npm\` or \`npx\`)
+- Follow ALL coding conventions, commit message formats, and architectural patterns specified
+- Reference these rules before running ANY shell commands or making commits
+
+---
+
+${formattedFiles.join('\n\n---\n\n')}
+
+---
+
+**REMINDER**: Before taking any action, verify you are following the conventions specified above.
+`;
+        } else {
+          // All files were CLAUDE.md, so no context to add
+          contextFilesPrompt = '';
+        }
+      }
+
       if (options?.continuationPrompt) {
         // Continuation prompt is used when recovering from a plan approval
         // The plan was already approved, so skip the planning phase
@@ -774,15 +812,53 @@ export class AutoModeService {
     );
 
     // Load project context files (CLAUDE.md, CODE_QUALITY.md, etc.) - passed as system prompt
-    // Note: When autoLoadClaudeMd is enabled, skip loading CLAUDE.md here since SDK handles it
+    const contextResult = await loadContextFiles({
-    // to avoid duplication. The SDK's settingSources will load CLAUDE.md from standard locations.
+      projectPath,
-    const { formattedPrompt: contextFilesPrompt } = autoLoadClaudeMd
+      fsModule: secureFs as Parameters<typeof loadContextFiles>[0]['fsModule'],
-      ? { formattedPrompt: '' }
+    });
-      : await loadContextFiles({
+
-          projectPath,
+    // When autoLoadClaudeMd is enabled, filter out CLAUDE.md to avoid duplication
-          fsModule: secureFs as Parameters<typeof loadContextFiles>[0]['fsModule'],
+    // (SDK handles CLAUDE.md via settingSources), but keep other context files like CODE_QUALITY.md
+    let contextFilesPrompt = contextResult.formattedPrompt;
+    if (autoLoadClaudeMd && contextResult.files.length > 0) {
+      const nonClaudeFiles = contextResult.files.filter(
+        (f) => f.name.toLowerCase() !== 'claude.md'
+      );
+
+      // Rebuild prompt without CLAUDE.md
+      if (nonClaudeFiles.length > 0) {
+        const formattedFiles = nonClaudeFiles.map((file) => {
+          const header = `## ${file.name}`;
+          const pathInfo = `**Path:** \`${file.path}\``;
+          const descriptionInfo = file.description ? `\n**Purpose:** ${file.description}` : '';
+          return `${header}\n${pathInfo}${descriptionInfo}\n\n${file.content}`;
         });
 
+        contextFilesPrompt = `# Project Context Files
+
+The following context files provide project-specific rules, conventions, and guidelines.
+Each file serves a specific purpose - use the description to understand when to reference it.
+If you need more details about a context file, you can read the full file at the path provided.
+
+**IMPORTANT**: You MUST follow the rules and conventions specified in these files.
+- Follow ALL commands exactly as shown (e.g., if the project uses \`pnpm\`, NEVER use \`npm\` or \`npx\`)
+- Follow ALL coding conventions, commit message formats, and architectural patterns specified
+- Reference these rules before running ANY shell commands or making commits
+
+---
+
+${formattedFiles.join('\n\n---\n\n')}
+
+---
+
+**REMINDER**: Before taking any action, verify you are following the conventions specified above.
+`;
+      } else {
+        // All files were CLAUDE.md, so no context to add
+        contextFilesPrompt = '';
+      }
+    }
+
     // Build complete prompt with feature info, previous context, and follow-up instructions
     let fullPrompt = `## Follow-up on Feature Implementation