How do I keep notes about a project that my Claude Code agents can read?

Put the short facts every session needs in CLAUDE.md, or in AGENTS.md if you also use Codex CLI or Gemini CLI. Keep longer notes as markdown files in the repository, then import them with @path from CLAUDE.md or point the agent to them when a task needs them. Anything in the repo is readable by the agent. What matters is what loads every time and what loads on demand.

The places Claude Code reads

Claude Code loads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it. Files in subdirectories load when Claude reads or edits a file there.

Step 1: start a CLAUDE.md

/init

/init analyzes the codebase and writes a starting CLAUDE.md with build commands, test instructions and conventions it finds. If one exists, it suggests improvements instead of overwriting.

Keep it to what you'd otherwise re-explain every session: build and test commands, layout, "always do X" rules. The docs suggest adding to it when Claude makes the same mistake twice or a review catches something Claude should have known.

Step 2: move longer notes into their own files

A decision log, an architecture overview or an API guide doesn't need to sit in every session's context. Put it in the repo:

docs/
  architecture.md
  decisions.md
  api-conventions.md

Then choose per file:

• Always loaded: import it from CLAUDE.md.

  Architecture overview: @docs/architecture.md

  Relative paths resolve from the file that contains the import. Imports can nest up to four levels. Wrap a path in backticks to mention it without importing it.

• Loaded on demand: just name it in CLAUDE.md ("decisions are in docs/decisions.md, read it before changing the data model"). Claude reads it with its normal file tools when it's relevant.

Step 3: scope rules to the code they cover

For rules that only matter in part of the codebase, use .claude/rules/ with a paths frontmatter:

---
paths:
  - "src/api/**/*.ts"
---
- Every endpoint validates its input with the shared schema.

A rule with paths loads only when Claude works with matching files.

Step 4: share one file with your other agents

If you also run Codex CLI or Gemini CLI, a single AGENTS.md avoids three copies of the same notes.

• Codex reads AGENTS.md before doing any work. It walks from the project root to the current directory, also reads ~/.codex/AGENTS.md, and stops adding files at 32 KiB by default (project_doc_max_bytes).

• Gemini CLI reads GEMINI.md by default. Set context.fileName in settings.json to include AGENTS.md:

  { "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }

• Claude Code reads AGENTS.md directly from v2.1.277 when there's no CLAUDE.md or CLAUDE.local.md in the working directory or above. If you have a CLAUDE.md, put @AGENTS.md at its top and add Claude-specific lines below.

Step 5: let auto memory handle the rest

Claude Code's auto memory saves notes Claude decides are useful later: your preferences, corrections you gave, project context it can't derive from the code. It lives in ~/.claude/projects/<project>/memory/, one directory per git repository, shared across worktrees. Run /memory to view or edit it, or to turn it off.

Limits of this approach

• Everything always loaded costs context. A long CLAUDE.md with many imports is read in every session. Keep the always-loaded part short.
• Notes are context, not rules. Claude can still ignore an instruction. For "never do X", the docs recommend a PreToolUse hook.
• Notes go stale. A decision log nobody updates misleads the agent. Ask the agent to update the file when it changes the thing the file describes.
• Private and shared notes mix easily. Anything committed is read by every teammate's agent. Use CLAUDE.local.md for yours.

With Kanbell

Kanbell is a macOS app (Apple Silicon) with one window per project. Each project has markdown notes, stored in the repository or kept private.

• Notes in the repo are markdown files in your working tree like any other. If an agent should read one, import it from CLAUDE.md or name it in the prompt, as in step 2. Kanbell does not feed notes to agents on its own.
• Private notes stay out of the repository. Use them for what you want next to the code but not in git or in a teammate's agent context.
• Tasks are separate. The project board, local or GitHub Issues, is what agents read through the kanbell CLI (kanbell list, kanbell show). On GitHub that access is read-only. Agents write with their own gh.

Kanbell has no account and no Kanbell server.