[Bug] Claude Code ignores CLAUDE.md canonical file rules, creates duplicate parallel implementations

BUG_REPORT_19042026.md

Bug Description

Bug Report — Claude Code ignoring project CLAUDE.md rules

Date: 2026-04-19
Project: E:\QuizFactory\kod (YouTube quiz video automation)
Model used: Opus 4.7 (1M context) — claude-opus-4-7[1m]
Severity: High (production-blocking)
Reporter: Dawid (owner)

---

Summary

Claude Code agent repeatedly creates new parallel helper scripts (tools/upload_*.py, new intro_builder_v*.py versions, new SEO modules) instead of using canonical entry points already defined in CLAUDE.md and established in the codebase. After explicit instruction to "run multilang_batch", the agent wrote its own wrapper around the pipeline. The net effect is that after ~7 days nobody — neither the user nor a fresh Opus audit — can tell which file is authoritative. Production is now blocked because metadata (SEO, thumbnails, translations) varies per run.

Rules in CLAUDE.md that were ignored

From E:\QuizFactory\kod\CLAUDE.md:

1. "Main entry: multilang_batch.py — ALWAYS use this" → Agent instead built tools/upload_one_long.py, tools/upload_two_longs.py, tools/upload_short.py as parallel entry points.
2. "Jedyny dozwolony uploader: yt_uploader.py" → Technically followed, BUT agent bypassed the auto-SEO that lives in yt_uploader.__main__ by calling YouTubeUploader.upload() directly from the new wrappers.
3. "Stability > features — don't refactor what works" → Agent created 3 versions of intro_builder (v1, v2, v4), 2 versions of SEO engine (seo_batch_fix.py + seo_updater.py), 3 flag registries (flag_registry.py, _verify.py, _vision.py).
4. "ALWAYS commit immediately after editing files" → Followed, but each commit introduced new parallel file instead of modifying existing.

Concrete violations (from read-only audit, 2026-04-19)

A. SEO bypass (3 parallel tag builders)

• seo_batch_fix._build_tags() (line 351) — canonical.
• seo_updater.py — parallel engine, different template, same goal. Both auto-apply. No one knows which runs.
• tools/retrofit_seo.build_tags() (line 34-44) — third copy, wraps #1.
• tools/upload_short.py, tools/upload_one_long.py, tools/upload_two_longs.py — all import #3 instead of #1.

B. Intro bypass (3 versions, 2 still imported)

• intro_builder.py (534 lines) — no imports anywhere — dead.
• intro_builder_v2.py (327 lines) — only integrate_intro_breaks.py imports it.
• intro_builder_v4.py (420 lines) — canonical, used by asset_assembler, integrate_units, result_card.
• None were deleted when successors landed.

C. Translation (i18n) scatter

• 118+ inline {"en": ..., "de": ..., "pl": ...} dicts across 11+ files.
• Locations: multilang_batch.py:73, pipeline3.py:100, yt_uploader.py:58, asset_assembler.py:1595, config.py:459, emoji_categories.py:166, video_builder.py:~100, intro_builder_v4.INTRO_HOOK_TPL, format_builders.GuessByEmojiBuilder._title_tpl, etc.
• No central i18n.py. Adding a language = editing 11+ files, missing one always.

D. Fallback data ignores topic

• quiz_generator_v9.py:393 — FALLBACK_DATA["guess_flag"] = hardcoded France, Germany, Japan, Brazil, Australia.
• Line 815: pads with this list when LLM returns too few.
• Line 865: re-pads after Gemini fact-check removes them as verdict=false.
• Result: "Arab Countries Flags Quiz" video ended with France, Germany, Japan flags as the last 3 questions. Gemini caught the error, but the blind pad re-introduced it.
• Agent saw this file during session but did not flag or fix it.

E. Fact-check filter too weak

• quiz_generator_v9.py:854 — keeps everything except verdict="false" AND confidence>=0.85.
• uncertain 0.0 (default after MAX_TOKENS truncation in llm_client.py:1700) passes.
• false 0.8 (Oman in Arab Quiz) passes.
• Entries with NO fact_check key at all pass.
• Should be whitelist (keep only verdict="true" AND confidence>=0.7), not blacklist.

F. Per-session new tools (12 files in tools/ since 2026-04-12)

tools/upload_short.py, upload_one_long.py, upload_two_longs.py, upload_publish_fix.py, upload_verify.py, retrofit_seo.py, seo_audit.py, srt_audit.py, flip_stuck_private.py, fix_questions_json.py, gen_gradients.py, clean_break_family.py.

Several are legitimate one-offs (audit, cleanup). But upload_*.py family, retrofit_seo.py could/should have been modifications to existing modules.

G. TTS voice config

• User explicitly said "DE without ref_text" three times across the session.
• Agent added DE ref_text in tts_master.py F5_REF_TEXT. Did not read git history to recover prior PL ref_text as instructed.
• Fixed only after third correction.

Pattern

Across the week, Claude treats "fix X" as "write new file that does X" rather than "modify existing file that already does X but…
Note: Content was truncated.