{"slug": "claude-code-memory-a-small-setup-that-keeps-project-rules-clear", "title": "Claude Code memory: a small setup that keeps project rules clear", "summary": "A concrete Claude Code setup for a small Python project called Receipt Lab keeps project rules in a root CLAUDE.md file, the current task in a short handoff, and discovered facts in auto memory, with the rounding policy that half a remaining cent rounds upward implemented in discount.py and verified via python3 -m unittest discover -s tests -v. The approach advises against promoting temporary findings to permanent rules and recommends using the /memory and /context commands to inspect what has loaded rather than guessing. The author notes the fresh-session check confirms important rules are present but does not prove a model will follow every rule in a larger task, so executable tests should be kept for requirements that must hold.", "body_md": "When Claude Code repeatedly forgets a project convention, the answer is usually a shorter, better-placed instruction—not a bigger opening prompt. Put stable rules in `CLAUDE.md`, keep the current task in a small handoff, and use auto memory for useful observations that survive a session.\n\nHere is a concrete setup for a tiny Python project called Receipt Lab. Its job is to apply whole-percent discounts to integer-cent amounts. The example is deliberately small so you can see whether the instructions change the work.\n\n## Separate three kinds of information\n\n- **A project rule:** amounts use integer cents. This belongs in the shared project instructions.\n- **A current task:** add tests for zero and full discounts. This belongs in the prompt or a short handoff file.\n- **A discovered fact:** the test runner is`unittest` , and the tests live in`tests/` . Keep it near the project instructions or in useful memory, with enough context to recheck it.\n\nDo not turn a temporary finding into a permanent rule just because it was true during one debugging session. “The test is failing today” will become stale. “Run this command to check the discount contract” remains useful.\n\n## Write a small project instruction file\n\nSave this as `CLAUDE.md` at the project root:\n\n```\n# Project: Receipt Lab\n\nAmounts are integer cents; use integer arithmetic, not floats or currency strings.\nFor this exercise, round a fractional final cent upward at one half.\nThe total_after_discount function returns the amount LEFT to pay.\nRun local checks with: python3 -m unittest discover -s tests -v\nDo not add a network service or a new dependency for this exercise.\n\nWhen reporting a result, include the exact input and output checked.\n```\n\nThe file tells Claude what matters and how to check it. It does not describe every file in the repository. Put detailed API contracts beside the code they govern, and refer to those paths when needed. Before adding another paragraph here, ask whether the next unrelated task really needs it.\n\n## Test the rules against real code\n\nSave this implementation as `discount.py`. The rounding policy is part of this exercise: half a remaining cent rounds upward. It is an explicit local choice, not a universal accounting rule.\n\n``` python\ndef total_after_discount(cents, percent):\n    if type(cents) is not int or cents < 0:\n        raise ValueError(\"cents must be a nonnegative integer\")\n    if type(percent) is not int or not 0 <= percent <= 100:\n        raise ValueError(\"percent must be an integer from 0 to 100\")\n    return (cents * (100 - percent) + 50) // 100\n```\n\nCreate `tests/test_discount.py`:\n\n``` python\nimport unittest\nfrom discount import total_after_discount\nclass DiscountTests(unittest.TestCase):\n    def test_quarter_off(self): self.assertEqual(total_after_discount(1200, 25), 900)\n    def test_no_discount(self): self.assertEqual(total_after_discount(1200, 0), 1200)\n    def test_free(self): self.assertEqual(total_after_discount(1200, 100), 0)\n    def test_invalid(self):\n        with self.assertRaises(ValueError): total_after_discount(1200, 101)\n```\n\nRun `python3 -m unittest discover -s tests -v`. Then start a fresh Claude Code session in the project and ask: “What amount representation, rounding rule and test command should you use here? Explain how you would test a zero-percent discount. Do not edit files.”\n\nCompare the answer with the instruction file. This checks whether the important rules are present in the session; it does not prove that a model will follow every rule in a larger task. Keep executable tests for requirements that must hold.\n\n## Inspect memory instead of guessing\n\nUse `/memory` to inspect the instruction and memory setup, and `/context` to see what has loaded. Current Claude Code also supports auto memory; its notes are distinct from the instructions you deliberately write. Review a remembered claim when the project changes, and correct stale entries instead of arguing with them in every new prompt.\n\nIf two files give conflicting guidance, resolve the conflict at its source. Adding “ignore the old rule” to a third file makes the project harder to reason about. Keep shared facts in version control and personal preferences in your personal scope. Never put credentials in an instruction file.\n\n## Use a handoff for work in progress\n\nA good handoff names the goal, files, verified facts, failed attempts and next action. It should let a fresh session continue without inventing the missing history. For Receipt Lab, “the 25-percent case passes; add 0 and 100 percent tests next” is more useful than a transcript of every intermediate thought.\n\nKeep that task state out of the permanent project rules once the work is done. The separation is practical: stable conventions should load repeatedly; a finished task should not keep steering next week's work.\n\n**What we checked:** The four Python unit tests passed. In one fresh Claude Code 2.1.281 session, the model read these files and correctly stated the integer-cent representation, half-up rule, remaining-total contract and test command. That is one instruction-following example, not a guarantee for future tasks.\n\nFor a task-specific procedure you invoke on demand, use a [Claude Code skill](https://somethingbig.ai/work/claude-code-skills). For a clean continuation, see the [context-window walkthrough](https://somethingbig.ai/work/claude-code-context-window).\n\n## Sources and version notes\n\nChecked against the current documentation on September 24, 2026. Command availability can vary with your installed version; check `claude --version`.", "url": "https://wpnews.pro/news/claude-code-memory-a-small-setup-that-keeps-project-rules-clear", "canonical_source": "https://somethingbig.ai/work/claude-code-memory", "published_at": "2026-09-24 00:00:00+00:00", "updated_at": "2026-09-24 07:31:11.369350+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "developer-tools"], "entities": ["Claude Code", "Receipt Lab", "discount.py", "unittest", "total_after_discount"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/claude-code-memory-a-small-setup-that-keeps-project-rules-clear", "markdown": "https://wpnews.pro/news/claude-code-memory-a-small-setup-that-keeps-project-rules-clear.md", "text": "https://wpnews.pro/news/claude-code-memory-a-small-setup-that-keeps-project-rules-clear.txt", "jsonld": "https://wpnews.pro/news/claude-code-memory-a-small-setup-that-keeps-project-rules-clear.jsonld"}}