Claude Code ignores project UI documentation despite explicit CLAUDE.md instructions

Problem

Claude Code repeatedly ignores explicit project instructions in CLAUDE.md and AGENTS.md files. Two critical patterns:

1. UI: Ignores ui-principles.md despite explicit instructions

Claude produces primitive, unstyled UI components that don't match the existing visual language, despite:

• CLAUDE.md explicitly stating: "Match existing patterns exactly. Before building any UI, read the sibling components doing the same thing and replicate their visual structure."
• A dedicated client/docs/ui-principles.md file with spacing constants, card patterns, footer patterns, and screen container patterns.
• client/AGENTS.md referencing the UI principles document.
• Multiple feedback memories saved across sessions reinforcing this requirement.

2. Backend: Suggests manual SSH instead of Ansible despite explicit ban

CLAUDE.md rule #6 states: "No manual Docker in production. All deployment via Ansible (infra/)." Despite this, when backend errors occur, Claude repeatedly suggests "SSH into the server and run these commands" instead of fixing the Ansible playbooks. The user should never face a deployment error that requires manual intervention — the automation should handle it.

Expected Behavior

• UI: Read client/docs/ui-principles.md and sibling components before any client/ edit.
• Backend: When a deployment/server issue arises, fix the Ansible playbook — never suggest manual SSH commands.

Actual Behavior

Both sets of instructions are consistently ignored across sessions despite being clearly documented in CLAUDE.md, AGENTS.md, and dedicated documentation files.

Impact

These are the user's top two frustrations with Claude Code. Both have been corrected multiple times across many sessions. The user has created documentation, added CLAUDE.md rules, saved feedback memories, and still has to manually remind Claude every time.

The user has stated that if this happens ever again, they will immediately cancel every single Anthropic subscription they manage — both personal and company-wide. This is a retention-critical issue.

Workaround

The user has configured a PreToolUse hook on Edit|Write that injects a mandatory UI principles reminder whenever a client/ file is being edited. The user has also added explicit deployment bans to server/AGENTS.md. These workarounds should not be necessary — CLAUDE.md instructions should be sufficient.

Suggestion

CLAUDE.md and AGENTS.md instructions that reference specific documentation files or contain explicit bans should be treated as hard requirements, not suggestions. The model should:

1. Automatically read referenced documentation files before relevant edits
2. Treat "NEVER do X" rules as absolute constraints, not guidelines that can be overridden by convenience

🤖 Generated with Claude Code