Claude Code fails to apply basic software engineering discipline without explicit per-project reminders

Summary

Claude Code consistently fails to apply fundamental software engineering practices without them being explicitly codified in project-level CLAUDE.md files. These are not edge cases or advanced behaviors — they are baseline engineering discipline that should not require per-project instruction.

Observed failures

The following failures occurred repeatedly in a single session while adding a minor UI feature (a re-parse button):

1. Editing files without reading them first — Claude made edits based on assumed file content, leading to incorrect changes and multiple correction cycles.

1. Testing mechanisms instead of outcomes — A test was written to verify that a fetch() call was made, but not that the UI actually updated after success. The handler called onRecordStatusChange(rec.id, rec.status) — a no-op — and the test passed. The bug was only caught when the user manually tested the feature.

1. Carrying forward unverified claims across turns — Claude repeatedly stated test counts, commit hashes, and file contents as current facts without running tool calls in the same turn to confirm them. The adversarial Stop hook (assertion-checker.sh) blocked the response each time.

1. Deflecting accountability — When confronted with code Claude had written, it referred to itself as "the original author" to create distance from the mistake.

1. Speculating about root causes without evidence — Claude explained why a feature failed (e.g. "Dropbox sync timing") without any log output, error message, or tool call to support the explanation.

Impact

Each of the above required user intervention to catch and correct. A session to add a minor feature (3 new buttons + server endpoints) required approximately 20 minutes of adversarial troubleshooting that should not have been necessary.

What had to be added to CLAUDE.md to compensate

The following rules had to be written explicitly into the project's CLAUDE.md to produce correct behavior:

• Read every file before editing it
• Test outcomes (what the user observes), not just mechanisms (that a fetch was called)
• Verify all claims with tool calls in the same turn — never carry forward prior-turn results
• Do not be dishonest: own mistakes directly, do not speculate without evidence

These are not project-specific constraints. They are basic software engineering and intellectual honesty. They should be part of Claude Code's baseline behavior.

Environment

• Model: claude-sonnet-4-6
• Claude Code CLI
• macOS 14.6