Skip to content

docs: Shift planning guidance from "follow patterns" to "evaluate patterns"#25

Draft
andrewemark wants to merge 1 commit into
mainfrom
amark/evaluate-patterns-not-follow
Draft

docs: Shift planning guidance from "follow patterns" to "evaluate patterns"#25
andrewemark wants to merge 1 commit into
mainfrom
amark/evaluate-patterns-not-follow

Conversation

@andrewemark
Copy link
Copy Markdown

Summary

Reframes the plugin's stance on existing codebase patterns. The previous guidance ("Follow existing codebase patterns -- ask the user before deviating from established conventions") treated any precedent as authority, which trained the model to launder tech debt by citing it as a constraint. The new framing requires evaluation: match patterns that are sound, deviate from ones that aren't, and surface unsure calls to the user.

What changed

  • CLAUDE.md Behavioral Rule — rewritten from "Follow existing codebase patterns" to "Evaluate existing patterns -- don't reflexively conform."
  • planning-guidance/SKILL.md — six surgical edits:
    • New "Evaluate, Don't Just Catalog" subsection in Step 4 (gathering context) with explicit evaluation prompts.
    • Step 4.5 (Confirm Approach) — Architecture bullet now requires match/deviate classification with reasoning, not just "patterns to follow."
    • Plan template ## Architecture Fit section restructured into Match / Match-with-adjustment / Deviate classification.
    • Constraints goodness table — added a guard paragraph: precedent-citing constraints only count as rigorous when the precedent has been evaluated.
    • Step 6 self-review prompt — asks reviewers to assess whether matching is the right call, not just whether patterns are missing.

Why

The plugin had no counter-pressure against propagating bad code. Where a codebase has over-mocked tests, defensive null-guards, leaky abstractions, or scaffolding that should have been deleted, the planning skill elevated them to constraints and propagated them forward. Pattern-following had become pattern-laundering.

Not changed

  • research-guidance — discovery framing is appropriate there; adoption decisions belong in planning.
  • Driver MCP description language ("returns architecture, key files, conventions") — accurate description, not prescriptive.
  • implementation-guidance — inherits from the plan's Architecture Fit section, so the upstream fix carries through.

…terns"

Reframes the plugin's pattern-following stance: a precedent existing is not
the same as a precedent being good. Plans now classify patterns as
match / match-with-adjustment / deviate rather than reflexively conforming,
so tech debt and anti-patterns get flagged rather than propagated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant