Personalisation: Building a Setup That Knows You

The issue: Most researchers who use Claude Code know about one or two personalisation mechanisms — usually CLAUDE.md, sometimes skills. They discover the rest by accident, or not at all. The result is a setup that is partially configured: Claude knows your project but not your preferences, or knows your preferences but not your project's history, or has no reusable skills and redoes from scratch every session.

Personalisation is not one file. It is a system with two distinct layers. This document maps the whole system and explains how to build it deliberately.

Two kinds of personalisation

Layer 1 — Claude Code mechanisms: The technical infrastructure Claude Code provides for persistent configuration. Claude reads these files automatically; they shape how Claude behaves before you type a single word.

Layer 2 — Project accountability files: Markdown files you maintain about your project — not instructions to Claude, but records that give Claude (and you) the context to work well. Claude reads these only when you ask, but asking costs nothing, and the files are as useful to you as to Claude.

Most coverage of personalisation focuses only on Layer 1. Layer 2 is at least as important for researchers, and almost never discussed as a deliberate practice.

Layer 1: Claude Code mechanisms

The complete map

~/.claude/                         ← global layer (always active)
  CLAUDE.md                        ← who you are, permanent preferences
  MEMORY.md                        ← facts Claude has learned about you
  commands/                        ← skills available in every project
    to-md.md                       →  /to-md file.pdf
    summarise.md                   →  /summarise paper.pdf
  settings.json                    ← default permissions, global MCP servers

your-project/                      ← project layer (active when launched from here)
  CLAUDE.md                        ← this project's context, conventions, structure
  .claude/
    commands/                      ← skills specific to this project
      extract-persons.md           →  /extract-persons register.pdf
      add-to-log.md                →  /add-to-log
    settings.local.json            ← project permissions, MCP overrides

Each mechanism, in brief

Global CLAUDE.md (~/.claude/CLAUDE.md) — your permanent identity across all projects. Who you are, your default citation style, how you want responses formatted, what Claude should never do. Write once; applies everywhere.

Project CLAUDE.md — this project's configuration. Folder structure, conventions, current phase, key terminology, standing constraints. Updated as the project evolves; irrelevant once the project ends.

Memory (~/.claude/MEMORY.md) — facts Claude has written down on your behalf during conversations. "Remember that I prefer output in Czech for public-facing work." Claude writes; Claude reads. See A.concept.memory for the full treatment.

Global skills (~/.claude/commands/) — reusable task prompts you want in every project. File conversion, your standard paper summary format, your citation check routine.

Project skills (.claude/commands/) — task prompts that only make sense here. An extraction prompt tuned to this source type; a log-entry format specific to this project's structure.

Hooks (.claude/settings.json or settings.local.json) — shell commands that run automatically when Claude takes certain actions (before a tool call, after writing a file, on session end). The most advanced mechanism; useful for automatically backing up outputs, logging actions, or enforcing constraints without relying on Claude to remember. Not necessary to start; worth knowing they exist.

MCP servers — external tools Claude can call during a session (Zotero, web search, databases). Configured globally or per project. See A.setup.settings-local.

What loads automatically vs. what you invoke

Mechanism Loaded automatically Invoked explicitly
Global CLAUDE.md Yes —
Project CLAUDE.md Yes —
Memory Yes —
MCP servers Yes —
Skills No — available as /command-name You type /command-name
Hooks Yes (trigger on events) —
Project accountability files No > Read _history.md and...

Layer 2: Project accountability files

These are not Claude Code features. They are a practice — a set of markdown files you maintain in your project folder that give Claude (and yourself) a richer picture of the project than CLAUDE.md alone can provide.

CLAUDE.md answers: What is the current state? Accountability files answer: How did we get here, why, and who did what?

The pattern

your-project/
  CLAUDE.md              ← current state, conventions, instructions
  _history.md            ← how the project developed; decisions and reasoning
  _ownership.md          ← who did what; how much of the work is AI-generated
  notes/
    progress.md          ← what has been done, what is in progress, what remains
    decisions.md         ← key choices extracted from the log

The underscore prefix is a convention: it sorts these files to the top of any directory listing, where they are easy to find and hard to overlook.

_history.md — the project narrative

Records decisions made, pivots, abandoned approaches, and open questions — with the reasoning behind each. Not a task list. Not a current-state summary. The narrative of how the project developed.

Why Claude needs it: When you return after a break, Claude reads the history and can tell you: what was decided, why, and what is still unresolved. Without it, Claude operates on the current state with no knowledge of how it came to be. You end up re-debating decisions already made.

Why you need it: It is the draft of your methodology section. It documents what you tried and abandoned. It is what you would tell a collaborator on their first day.

See A.markdown.history for a full treatment of this file.

_ownership.md — the attribution record

Records who did what across the project. Not in a forensic sense — but as an honest accounting of the distribution of work between you and Claude, for the purposes of disclosure and attribution.

Why it matters: If these materials are published, credited, or submitted as part of your professional record, you need to know what you can claim and what requires qualified attribution. A history of AI collaboration does not invalidate your authorship — but a vague or inaccurate claim about it does.

What it contains:

This is the file format used in this project's own _ownership.md. The framework that makes it tractable is in B.ownership.

progress.md — current task state

A running log of what has been done, what is in progress, and what remains. Not the narrative of why — that is _history.md — just the practical state of the work.

# Progress log

## 2025-03-14
Done: processed registers 1–24. Extracted 480 deposition entries.
In progress: cross-referencing name variants for Guilhem.
Next: registers 25–35; resolve [?] flags from last batch.
Open: Duvernoy edition discrepancy — three entries differ, cause unknown.

Why Claude needs it: Read at session start, it tells Claude where you left off without you having to reconstruct it from memory. At the end of a session, ask Claude to append a progress entry — it costs thirty seconds and makes the next session's start frictionless.

When to add other files

These are the core three. Others can be added when the project warrants:

What a complete setup looks like

A researcher who has built both layers has something like this:

Global layer (set up once, maintained occasionally):

Per project (built at project start, maintained throughout):

When this researcher launches Claude Code from their project folder, Claude already knows:

And they have skills ready to invoke without rewriting prompts, and a record ready for any disclosure they need to make.

How to build it deliberately

Step 1: The global layer (do this once)

If you have not done it, this is the highest-return investment. It takes 20 minutes and applies to every project you ever run.

> Create a global CLAUDE.md at ~/.claude/CLAUDE.md with a template.
  Include: who I am, my field, my citation style, my output preferences,
  and two or three things I always want Claude to know.
  Keep it to one page.

Then: > Create ~/.claude/commands/ and add a /to-md skill and a /summarise skill.

Step 2: Each new project

When you start a project:

> Create a CLAUDE.md for this project. I am working on [topic].
  The folder structure is [describe]. The main conventions are [describe].
  Ask me any questions you need to make it accurate.

Then immediately:

> Create _history.md and notes/progress.md. Add today's date and
  a first entry: project started, initial setup done.

Starting these files at day one costs nothing. Reconstructing them six months later costs significant effort.

A practical note: the setup builds as you discover, not upfront.

The advice above assumes you know on day one what belongs in these files. Often you do not. A project that starts without a CLAUDE.md and creates one after several sessions — when the structure, conventions, and recurring patterns have become clear — is not behind. It is being accurate rather than aspirational.

The same is true for skills and hooks. A /update-meta-docs command only makes sense once you have updated meta-documents manually enough times to know exactly what "update" means for each file. A hook that reminds you to run it only makes sense once you know the command exists. The right time to create infrastructure is when you understand what it should do — and that understanding comes from the work itself.

The workshop materials these docs are based on are a direct example. CLAUDE.md, the /update-meta-docs command, and the Stop hook for this project were all created in session four — after more than fifty documents existed. The delay was not a mistake. The project ran without that infrastructure, the infrastructure needed to reflect the actual project, and creating it early would have produced a CLAUDE.md that described a project not yet understood.

What "start at day one" really means: create the file and start it, even with a minimal entry. A one-line CLAUDE.md is better than none — it is a placeholder that will grow. The same for _history.md. You do not need to know what will go in them; you need to start the habit before the project accumulates enough that starting feels like reconstruction.

Step 3: As the project runs

At each session start:

> Read CLAUDE.md and notes/progress.md. Tell me where we left off.

At each session end:

> Append a dated entry to notes/progress.md summarising what we did
  today, what is in progress, and what comes next.

When a significant decision is made:

> Append an entry to _history.md recording the decision we just made
  and the reasoning behind it.

When you realise you keep repeating the same thing to Claude: Add it to CLAUDE.md if it is project-specific. Ask Claude to remember it if it is personal and cross-project.

Step 4: Maintenance

Quick diagnostic

Claude keeps not knowing things you have told it before — check whether those things are in CLAUDE.md or Memory, or whether you are only telling Claude in conversation.

You spend the first ten minutes of every session re-establishing context — you need a CLAUDE.md and a progress file.

You cannot remember why you made a past decision — you need a _history.md.

You are unsure how to characterise AI's role in your work for a publication or report — you need an _ownership.md.

Claude has skills in one project but not in another where they would be useful — those skills belong in ~/.claude/commands/ (global), not only in .claude/commands/ (project-local).

You keep rewriting the same extraction prompt slightly differently each session — that prompt belongs in a skill file.

Related