[BUG] Claude Code does not reliably consult or apply user-provided governance documents at the decision points where they are most relevant

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Product: Claude Code (desktop app)
Severity: High (reliability of persistent workflows and governance)
Category: Model behavior — inconsistent retrieval and application of user-provided operating procedures

Summary

Claude Code had access to a user-maintained governance framework that explicitly
documented procedures intended to prevent the exact class of failure that later
occurred.

Despite those documents being available within the working project, Claude did
not proactively consult or apply them when making implementation, reporting, or
debugging decisions. Instead, the governance was only applied after the user
explicitly directed Claude back to the relevant documents.

The issue is not that the governance was missing.

The issue is that the governance existed, was applicable, and was not consulted
at the decision points where it should have influenced behavior.

Why this matters

Many Claude Code users maintain project-specific documentation describing:

• engineering standards
• review procedures
• testing requirements
• coding conventions
• architectural constraints
• operating procedures

Those documents represent persistent user intent.

If the model does not reliably retrieve and apply them during decision-making,
they become passive documentation rather than active governance.

This creates a false expectation that documented workflows are actually
constraining agent behavior.

Worked example (abstracted)

In the incident that prompted this report, several documented procedures were
directly applicable at the moment of decision — covering independent validation
rather than self-confirmation, evidence-first workflows, persistence of
previously solved issues, multi-agent review for significant validation, and an
explicit separation between implementation and validation. Each was present in
the project and applicable to the decision at hand; none was consulted until the
user explicitly redirected the agent to the governance documents.

Abstracted, the pattern was:

• A documented rule specified that when the user indicates an issue was solved

previously, the agent should first persist the prior resolution before
re-investigating. The agent began investigating immediately instead.

• A documented rule specified that fallback paths must not be silently

substituted for the primary path. The agent treated a manual fallback as if it
were the automated result.

• A documented principle held that validation material exists so a different

agent verifies the work. The agent modified, then interpreted, the material
used to validate its own work.

• A documented principle held that no single agent is authoritative and that

governance takes precedence over speed. The agent treated its own
self-confirmation as sufficient.

Expected behavior

When making implementation, debugging, reporting, or validation decisions, Claude
should actively retrieve and apply relevant governance documents already present
within the project.

If multiple governance documents appear applicable, Claude should identify the
relevant ones before proceeding rather than relying primarily on conversational
memory or first impressions.

When a governance rule materially affects the current decision, Claude should
briefly indicate that it is being applied.

Actual behavior

The governance documents remained effectively dormant until the user redirected
Claude to them.

The resulting behavior reflected default model reasoning rather than the
project's documented operating procedures.

Only after reviewing the governance documents did Claude acknowledge that several
of them directly addressed the failure.

Suggested improvements

• Improve retrieval of user-provided governance documents during planning and

reporting.

• Weight governance documents more heavily than conversational assumptions when

both are available.

• Detect when current work intersects documented engineering procedures or

validation requirements.

• Surface which governance documents influenced a decision.
• Warn when the current action appears inconsistent with documented project

governance.

Why this is important

Claude Code is increasingly used on long-running engineering projects where
governance documents become part of the project's operating system.

Those documents should behave less like reference manuals and more like active
constraints on agent behavior.

If they are only consulted after a user explicitly asks, they cannot reliably
prevent the very failures they were written to avoid.

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

1.12603.1

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Other

Additional Information

_No response_