docs(claude): add scope discipline and architectural priority rules

[carlos-alm]

Summary

Adds two new top-level guidance callouts to CLAUDE.md alongside the existing rule blocks:

• Scope discipline — open issues, don't expand scope. When an unrelated bug, pre-existing defect, or larger refactor surfaces during work, file a GitHub issue with gh issue create and keep going. Only fix inline when it directly affects the result of the current task. Reinforces the existing one-PR-one-concern rule by giving agents an explicit place to put findings instead of bundling them in.
• Prioritize the best architecture, not the smallest diff. Don't default to the simplest or most localized fix. Choose the approach that fits the codebase's architecture best, even when that means larger changes, moving code across modules, or restructuring an abstraction. A larger diff that leaves the design healthier is preferable to a small diff that entrenches a poor structure.

These two rules are paired intentionally: the architecture rule pushes for the right fix, and the scope rule keeps that fix from ballooning into an unrelated refactor inside the current PR.

Test plan

• No code changes — docs only
• Diff inspection: two callouts inserted before ## Codegraph Workflow, no other changes

[claude]

Claude finished @carlos-alm's task —— View job

---

Reviewing PR: docs(claude): add scope discipline and architectural priority rules

Todo List

• Read CLAUDE.md file to understand the changes
• Apply Phase 1: Root Cause Analysis
• Apply Phase 2: Configuration Change Detection
• Apply Phase 3: Test Integrity Check
• Apply Phase 4: Code Quality Assessment
• Apply Phase 5: Backlog Compliance Rating
• Provide Final Assessment and Rating

Changes Analysis

The PR adds two new guidance callouts to lines 13-15 in CLAUDE.md:

1. Scope discipline rule (line 13): "When you encounter a problem unrelated to the current task — pre-existing bugs, code that needs a bigger refactor, or any defect that does not directly affect the result of what you're doing — open a GitHub issue with gh issue create and keep going."

2. Architectural priority rule (line 15): "Do not default to the simplest or most localized fix. Choose the approach that fits the codebase's architecture best, even when that means larger changes, moving code across modules, or restructuring an abstraction."

---

Root Cause Analysis

Problem Being Solved: The PR addresses two common anti-patterns in AI-driven development: (1) scope creep where agents try to fix unrelated issues they encounter, leading to unfocused PRs, and (2) agents defaulting to minimal changes that may entrench poor architectural decisions rather than making proper architectural improvements.

Why This Approach: These are documentation-only changes that provide explicit guidance to Claude Code agents. The approach is justified because it creates clear decision criteria for when to fix vs. defer issues, and explicitly encourages architectural thinking over diff minimization.

Risk Assessment: Very low risk. Documentation changes only, no code modifications. The guidance aligns with established software engineering best practices around separation of concerns and architectural health.

Backlog Compliance

• Zero-dep: ✓ — No new dependencies, documentation only
• Foundation-aligned: ✓ — Fully aligned, reinforces core principles around focused changes and architectural health
• Problem-fit: 4 — Directly improves AI agent decision-making and reduces common failure modes (scope creep, poor architecture choices) that waste developer tokens and time
• Breaking: No — Pure documentation addition, no behavior changes
• Tier: 1

Critical Concerns

None identified. This is well-crafted documentation that addresses real problems with clear, actionable guidance.

Quality Assessment

The documentation additions are:

• Well-positioned: Placed appropriately with other top-level guidance rules
• Clear and actionable: Both rules provide specific actions (gh issue create, "choose the approach that fits the codebase's architecture best")
• Complementary: The two rules work together - architectural rule encourages proper design, scope rule prevents it from expanding beyond the current PR
• Consistent: Matches the tone and style of existing guidance callouts
• Specific: References concrete tools (gh issue create) and decision criteria

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE
• Reasoning: This is high-quality documentation that addresses real problems with AI-driven development. The guidance is clear, actionable, and well-positioned. The scope discipline rule will help prevent unfocused PRs, while the architectural priority rule encourages better long-term design decisions. No concerns identified.

Minor note: The guidance could potentially benefit from concrete examples of when to apply each rule, but the current wording is sufficiently clear for practical use.

---

[greptile-apps]

Greptile Summary

This PR adds two new top-level guidance callouts to CLAUDE.md for Claude Code agents working in this repo. The changes are documentation-only with no code impact.

• Scope discipline rule instructs agents to file a GitHub issue via gh issue create when they encounter unrelated bugs or larger refactors, keeping PRs focused on one concern — reinforcing the existing "One PR = one concern" convention already stated later in the file.
• Architecture priority rule instructs agents to choose the architecturally correct fix over the smallest diff, explicitly permitting larger changes when they leave the design healthier.

Confidence Score: 5/5

Documentation-only change with no code modifications; safe to merge.

Both new callouts are well-scoped, clearly worded, and consistent with the existing rule set in CLAUDE.md. The two rules are intentionally complementary — architecture priority encourages the right fix, scope discipline prevents it from expanding into unrelated work. No contradictions with existing conventions (e.g., 'One PR = one concern' in the Git Conventions section) were found.

No files require special attention.

Important Files Changed

Filename	Overview
CLAUDE.md	Adds two new blockquote callout rules (scope discipline and architecture priority) before the Codegraph Workflow section; formatting and wording are consistent with existing callouts, no contradictions with existing rules.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Agent encounters a problem] --> B{Related to current task?}
    B -- Yes --> C{Smallest diff or best architecture?}
    B -- No --> D[Open GitHub issue via gh issue create]
    D --> E[Keep going on current task]
    C -- Smallest diff --> F[❌ Reject: entrenches poor structure]
    C -- Best architecture --> G[✅ Proceed: even if larger diff]
    G --> H{Unrelated side effects found?}
    H -- Yes --> D
    H -- No --> I[Commit focused PR]

Loading

_{Reviews (1): Last reviewed commit: "docs(claude): add scope discipline and a..." | Re-trigger Greptile}