Claude Code memory: a small setup that keeps project rules clear

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.

Here 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.

Separate three kinds of information #

• A project rule: amounts use integer cents. This belongs in the shared project instructions.
• A current task: add tests for zero and full discounts. This belongs in the prompt or a short handoff file.
• A discovered fact: the test runner isunittest , and the tests live intests/ . Keep it near the project instructions or in useful memory, with enough context to recheck it.

Do 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.

Write a small project instruction file #

Save this as CLAUDE.md at the project root:

Amounts are integer cents; use integer arithmetic, not floats or currency strings.
For this exercise, round a fractional final cent upward at one half.
The total_after_discount function returns the amount LEFT to pay.
Run local checks with: python3 -m unittest discover -s tests -v
Do not add a network service or a new dependency for this exercise.

When reporting a result, include the exact input and output checked.

The 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.

Test the rules against real code #

Save 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.

def total_after_discount(cents, percent):
    if type(cents) is not int or cents < 0:
        raise ValueError("cents must be a nonnegative integer")
    if type(percent) is not int or not 0 <= percent <= 100:
        raise ValueError("percent must be an integer from 0 to 100")
    return (cents * (100 - percent) + 50) // 100

Create tests/test_discount.py:

import unittest
from discount import total_after_discount
class DiscountTests(unittest.TestCase):
    def test_quarter_off(self): self.assertEqual(total_after_discount(1200, 25), 900)
    def test_no_discount(self): self.assertEqual(total_after_discount(1200, 0), 1200)
    def test_free(self): self.assertEqual(total_after_discount(1200, 100), 0)
    def test_invalid(self):
        with self.assertRaises(ValueError): total_after_discount(1200, 101)

Run 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.”

Compare 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.

Inspect memory instead of guessing #

Use /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.

If 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.

Use a handoff for work in progress #

A 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.

Keep 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.

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.

For a task-specific procedure you invoke on demand, use a Claude Code skill. For a clean continuation, see the context-window walkthrough.

Sources and version notes #

Checked against the current documentation on September 24, 2026. Command availability can vary with your installed version; check claude --version.