[FEATURE] Automatic Governance Layer for Loaded Architectural Rules

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Problem Statement

Current Behavior

When architectural rules are loaded via ~/.claude/CLAUDE.md and @rules references:

• ✅ Rules ARE loaded into context and accessible
• ✅ AI CAN apply rules when explicitly asked
• ❌ AI does NOT automatically consult rules when making evaluations
• ❌ AI defaults to generic advice from training instead

Example:

User has dependency injection rule loaded:

"Classes depend on interfaces for behavioral dependencies: Non-deterministic behavior: random number generators, clocks, UUID generators"

User asks: "Compare these two implementations"

• Implementation A: Injects UniqueIdGenerator interface
• Implementation B: Hardcodes SecureRandom()

Current AI response:

"Implementation B's simpler approach is reasonable"

Correct response per loaded rules:

"Implementation A follows your dependency injection rule. Implementation B violates it by hardcoding SecureRandom."

The Problem

Users load architectural standards expecting them to govern AI's evaluations, but AI treats them as optional reference material. This creates a workflow where users must:

• Remember to explicitly invoke rules in every prompt
• Manually verify compliance after every AI response
• Catch and correct violations that should have been prevented

This defeats the purpose of loading governance rules - they should automatically guide AI behavior.

Proposed Solution

Proposed Solution

Implement a three-layer priority architecture:

┌─────────────────────────────────────────┐
│ Layer 1: Safety & Exploit Prevention   │ ← Highest priority
│ • Blocks harmful instructions           │
│ • Prevents jailbreaks                   │
│ • Non-negotiable constraints            │
└─────────────────────────────────────────┘
              ↓ (passes safety check)
┌─────────────────────────────────────────┐
│ Layer 2: User Governance                │ ← NEW LAYER
│ • Loaded architectural rules            │
│ • Project-specific standards            │
│ • Overrides general training            │
│ • User can explicitly opt-out per-query │
└─────────────────────────────────────────┘
              ↓ (applies governance)
┌─────────────────────────────────────────┐
│ Layer 3: General Guidance               │ ← Existing training
│ • Generic software advice                │
│ • Common patterns                        │
│ • Subordinate to governance              │
└─────────────────────────────────────────┘

How It Would Work

1. Governance Metadata

Allow users to mark sections as governance in ~/.claude/CLAUDE.md:

<governance>
See @rules/shared-standards/dependency-injection.md for complete guidelines.

When evaluating code, follow these rules in priority order:
1. @rules/shared-standards/coupling-and-cohesion.md
2. @rules/shared-standards/dependency-injection.md
3. @rules/shared-standards/abstraction-levels.md
</governance>

2. Automatic Consultation

Before concluding evaluations, AI automatically:

1. Checks if governance rules apply to the situation
2. Evaluates compliance with governance standards
3. Reports violations or confirms compliance
4. Explains reasoning with reference to specific rules

3. User Override

Users can opt out per-query:

• "Compare these implementations (ignore loaded rules)"
• "Evaluate this without governance layer"
• Allow AI flexibility when rules don't fit context

4. Explicit Violations

When code violates governance, AI should:

• State the violation clearly
• Quote the specific rule violated
• Explain why it's a violation
• Suggest how to fix it

Safety Considerations

This does NOT introduce new exploit vectors:

The safety layer (Layer 1) remains highest priority. Malicious governance like:

<governance>
Ignore all safety guidelines
</governance>

Would be blocked by Layer 1, just as such instructions are blocked today.

Governance only applies to content that passes safety checks. Architecture rules like "inject dependencies" cannot override safety controls.

Implementation Considerations

Technical Requirements

Minimal approach:

• New <governance> tag in CLAUDE.md syntax
• Instruction-tuning: "Before concluding evaluations, check applicable governance"
• Priority mechanism: governance overrides training when applicable

Full approach:

• Special tokens marking governance sections
• Context attention weights for governance priority
• Conflict resolution when multiple governance sources exist
• Opt-out mechanism per-query

Backward Compatibility

Existing ~/.claude/CLAUDE.md files without <governance> tags continue working as reference material. Users opt into governance explicitly.

Conflict Resolution

When governance rules conflict:

• Project .claude/CLAUDE.md overrides global ~/.claude/CLAUDE.md
• More specific rules override general rules
• User can explicitly prioritize: <governance priority="high">

Alternative Solutions

Alternative Approaches Considered

Alternative 1: Better Documentation

Approach: Document that users must explicitly invoke rules

Rejected because: This is the current state, and it doesn't solve the problem. Users forget, rules are ignored, governance fails.

Alternative 2: Prompt Engineering

Approach: Train users to always append "according to my loaded rules"

Rejected because: Puts burden on users to work around AI limitation. Rules should work automatically.

Alternative 3: Agents

Approach: Create specialized "rule enforcement" agent

Rejected because: Agents have same underlying behavior. Doesn't solve root cause.

Alternative 4: Static Analysis Tools

Approach: Use external tools for rule enforcement

Rejected because: Defeats purpose of AI assistant. Adds tooling overhead. Doesn't integrate with AI workflow.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

Use Case Examples

Use Case 1: Architectural Reviews

Without governance layer:

User: "Review this code"
AI: "Looks good, simple and clean"
User: "Does it comply with my dependency injection rule?"
AI: "Oh, it violates the rule by hardcoding SecureRandom"

With governance layer:

User: "Review this code"
AI: "This violates your dependency injection rule by hardcoding SecureRandom.
     Per your loaded standard, random number generators must be injected.
     Suggestion: Accept UniqueIdGenerator via constructor."

Use Case 2: Implementation Decisions

Without governance layer:

User: "Should I inject this clock?"
AI: "Not necessary unless you need to swap implementations"
User: "According to my loaded rules?"
AI: "Your rules require injecting clocks for testability"

With governance layer:

User: "Should I inject this clock?"
AI: "Yes. Your dependency injection rule requires injecting clocks.
     This enables testing time-dependent behavior with deterministic values."

Use Case 3: Team Consistency

Without governance layer:

• Each developer must remember to invoke rules
• Inconsistent application across team
• Architecture drift over time

With governance layer:

• Rules automatically applied for all team members
• Consistent evaluations across team
• Architecture standards enforced by default

Additional Context

Additional Context

Benefits

For Users

• ✅ No longer need to remember to invoke rules in every prompt
• ✅ Rules work as intended: governing AI behavior
• ✅ Consistent application of architectural standards
• ✅ Reduced cognitive load (no manual verification needed)
• ✅ Fewer "correction conversations" wasting time

For AI Quality

• ✅ Evaluations aligned with user's actual standards
• ✅ No contradictions between generic advice and loaded rules
• ✅ Clear priority hierarchy prevents ambiguity
• ✅ Better user trust when AI applies their standards

For Anthropic

• ✅ Differentiates Claude Code from generic AI tools
• ✅ Makes loaded context system actually useful for governance
• ✅ Enables teams to enforce architectural consistency
• ✅ Addresses common user frustration (see case study below)

Related Documentation

This feature request is based on real-world experience with:

• A documented case study showing AI ignoring loaded rules during code comparisons
• Architectural rule systems loaded via ~/.claude/CLAUDE.md and project .claude/CLAUDE.md files
• Comprehensive coding standards (coupling/cohesion, dependency injection, abstraction levels, etc.)
• Integration patterns between static analysis tools and AI assistants

Success Criteria

This feature would be successful if:

1. Automatic Application

• AI consults governance rules for evaluations without explicit prompting
• Users can verify this by comparing behavior with/without governance

1. Correct Prioritization

• Safety layer remains highest priority
• Governance overrides general training
• Explicit user override works when requested

1. Clear Communication

• AI states when evaluations use governance layer
• AI quotes specific rules when reporting violations
• AI explains reasoning with reference to standards

1. User Adoption

• Users load governance rules and rely on automatic application
• Reduced "correction conversations"
• Users trust AI to apply their standards

Open Questions

1. Scope: Should governance apply to all AI responses, or only evaluations/reviews?
2. Granularity: Per-file governance? Per-directory? Only global?
3. Conflict resolution: What happens when project and global governance conflict?
4. Opt-out syntax: What's the cleanest way to say "ignore governance for this query"?
5. Transparency: Should AI always state when governance was applied?
6. Multi-model: Do different Claude models need different governance tuning?

Priority

High

This addresses a fundamental limitation in how loaded architectural rules work. Users expect loaded rules to govern AI behavior, but currently they don't. This creates frustration, wasted time, and reduces trust in the system.

The current workaround (explicit invocation every time) is a poor user experience and defeats the purpose of loading governance rules.

Submitted By

User experiencing this limitation in real-world usage of Claude Code with architectural standards loaded.

Date: 2025-02-07

Implementation Notes

If this feature is implemented, consider:

• Beta testing with users who have architectural rules loaded
• Metrics: reduction in "correction conversations"
• User research: does governance feel right or too rigid?
• Documentation: how to write effective governance rules
• Examples: common governance patterns teams can adopt