What to put in CLAUDE.md for QA investigations

Explain what the project manages

Describe the project and the sources to check. For CSV work, include what each column means, when a value may be updated, and how to record something that is still unknown.

Keep the shared context short and link to documents with more detail. This gives you fewer places to update when the project changes.

An example for a CRUD inventory project

This example uses a fictional project that manages a CRUD inventory. Adjust the folder names and decision process to match your project.

# Purpose
Maintain an evidence-backed CRUD inventory for each feature.

# Investigation process
- Check the target branch first
- Separate facts, hypotheses, and open questions
- Cite the files supporting each conclusion
- Mark findings without evidence as "Needs verification"

# Edit boundaries
- Do not modify files during investigation
- If an update is needed, first describe its scope and proposed diff

# Verification
- Inspect the diff after updating the inventory
- Ask the responsible person about technical uncertainties

Check permission settings as well as the instructions

CLAUDE.md tells the model about the project and how you want it to work. Access permissions are controlled separately. Check the environment’s settings for confidential information and allowed operations.

Review the results and any changes, even when you have written clear instructions. The official documentation also states that strict adherence to instructions is not guaranteed.

Update the guide when the same question keeps coming up

You can improve the guide as you use it. If logical and physical deletion keep getting confused, for example, add a definition and an example of each.

Check for outdated or conflicting instructions when the project changes. Keep the guide short enough to read through and review.