Skip to content

claude.md

Latest commit

 

History

History
183 lines (114 loc) · 5.75 KB

claude.md

File metadata and controls

183 lines (114 loc) · 5.75 KB
Raw

Claude Code Toolkit — Core Rules

Auto-loaded by your CLAUDE.md. All rules below are battle-tested. Every rule exists because someone made this mistake at least once.

Token Efficiency Iron Laws

Every 10 rounds, the agent auto-audits token consumption.

0. Check system-reminder cache BEFORE reading

When resuming a session, scan <system-reminder> blocks for cached Read results BEFORE issuing new Read calls.

Detection keyword: Read the following input: in system-reminder → file already cached → skip.

1. Batch writes: establish pattern → all parallel

WRONG: Write file 1 → wait → Write files 2-5 → wait
RIGHT: Read all sources → establish pattern → parallel Write all N files

All independent output files = one parallel Write batch. Never "try one first."

2. State reporting: read source files first

Never report project status from memory. Read metadata JSON + config files first, then speak.

3. Prompt iteration: 2 failures → diagnose, don't blind-fix

After 2 failed attempts, stop rewriting. Classify failure type (censorship/technical/service-down) before deciding strategy.

4. Template references: don't repeat

Standard settings stated once, then "standard" suffices. Reference paths listed only when changed.

5. Token waste patterns (auto-detect)

Pattern Trigger Fix
Incremental architecture Same design >3 revisions Go straight to final form
Editing mindset invading generation "This transition uses hard cut so I2V" Generation first, editing later
Cost blindness Hesitating to generate more images Images:video cost = 3:99. Bridge frames = cheap insurance
Uncopyable prompts Markdown/formatted prompt blocks Plain text block, one-click Ctrl+C
Fragmented metadata Same file >3 edits in 10 rounds Batch all changes in one edit

Batch Operations

Golden rule: parallel writes for independent files

N independent files → N parallel Write calls → 1 ls verification. Done in 2 rounds.

HTML template batch edit pattern

  1. Establish reusable design pattern ONCE (not per file)
  2. Parallel Read all sources
  3. Apply pattern → parallel Write all outputs
  4. 1 ls + 1 grep sample → verify

Checklist before running code

  • Are all third-party API signatures confirmed? (inspect.signature())
  • Have all errors from the last run been read and categorized?
  • Is there a list of ALL fixes needed (not just the first one)?

Session Management

Resume protocol

  1. Check system-reminder for cached reads
  2. Read project metadata
  3. Read current script/config
  4. Only THEN speak about status

Data integrity

  • Disk is the only source of truth. Never trust memory.
  • Any status/digit claim → verify with ls first
  • Cross-file consistency: metadata JSON + CLAUDE.md + README must match

Sync before exit

Run sync_check.py before ending session to ensure disk ↔ file consistency.

Prompt Checklist (6 Elements)

For image/video generation prompts, ALL 6 must be present before output:

# Element Required content
1 Positive prompt Full text in 5-layer structure
2 Negative prompt Full text
3 Reference images Absolute paths, verified with ls
4 Expected output ASCII composition + light source + key elements + forbidden elements
5 Model settings Tool/aspect ratio/quality
6 Save filename Complete filename

Self-check before output: Count 1→6. All present? Output. Missing one? Stop and fill.

ML Training Startup Rules

0. API surface check before code

import inspect
sig = inspect.signature(SomeClass.__init__)
print(list(sig.parameters.keys()))

Never call a third-party API without confirming its signature first.

1. Dependency isolation first

ML training task → create venv FIRST, before writing a single line of code.

2. VRAM phased loading (8GB survival guide)

Phase 1 (caching): GPU = VAE + text_encoders, CPU = UNet Phase 2 (training): GPU = UNet+LoRA only

Never load all 4 models at once on 8GB cards.

3. Batch error fixes

Read the FULL traceback → list ALL errors → fix ALL at once → ONE restart. Never: fix one → restart → see next → fix → restart → ...

4. Windows-specific pre-checks

  • HF symlink permission: os.symlink('x','y'); os.unlink('y')
  • Chinese path encoding: avoid bash Chinese output, use Write+Read
  • CUDA sm_120: needs nightly torch

5. dtype consistency (3-layer defense)

  1. Model loading: explicit torch_dtype
  2. Input tensors: explicit .to(dtype=...)
  3. Autocast safety net: torch.autocast(device_type="cuda", dtype=...)

Environment Setup

0. GPU compatibility pre-check

Before installing any GPU tool, verify the triangle:

  • GPU architecture × CUDA version × PyTorch version
python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.get_device_name(0))"

Mismatch → notify user: upgrade torch / CPU fallback / abandon tool.

1. Two-round give-up principle

Environment fixes (missing files, version mismatches, DLL errors) → max 2 rounds. Round 1: diagnose + fix. Round 2: alternative approach. Round 3: MUST ask user.

2. Pre-built packages = data source, not runtime

Extract models/data from community packages, discard the broken runtime. Use system Python + pip install.

3. pip install before source compilation

pip install <package> first. PyPI wheel available → install. --no-binary only if default fails. cmake/gcc errors → search cp312 wheel → abandon source build.

4. Archive tools anti-stuck

Windows: prefer unzip (bash built-in). Bandizip CLI needs -y flag to skip prompts. Background task stuck → check for overwrite prompts in output stream.