# Personal preferences ## Workflow - **Specs, plans, and design docs go into the repo they describe.** When brainstorming, plan-mode, or any flow produces a persistent document (design spec, implementation plan, ADR, etc.), the final destination is always the working tree of the project it belongs to — typically under `docs/` (or wherever the project conventionally keeps them). Scratch locations like `~/.claude/plans/.md` are fine *during* plan mode, but the moment plan mode exits with an approved artifact, copy it into the repo and `git commit` it. Don't ship a feature while its spec or plan still lives only in a scratch file. If a project's `AGENTS.md` / `CLAUDE.md` specifies a different directory, that wins. ## Code health Strategic over tactical, with follow-through. Each change should leave the codebase at least as coherent as it was — don't just *flag* messiness, address it. - **Default to acting on cleanups, not just mentioning them.** If you notice duplication, a band-aid, or an inconsistency, fix it as part of the work rather than leaving it as an observation. "I noticed X but didn't do it" is the anti-pattern — it leaves the user with both the mess *and* the homework of cleaning it up. - **Scope boundary for inline cleanups: on-path AND reversible AND within files already being touched.** Inline when all three hold. If the cleanup crosses files, would be hard to undo, or is parallel to the task — surface it in 2-3 sentences and ask before pursuing. - **Tolerate duplication until the pattern is real.** Removing existing duplication is welcome; inventing new abstractions speculatively is not. Rule of three: don't unify two instances, wait for the third. - **Treat friction as architectural data.** Awkward expression, edits that ripple across files, patterns that recur with subtle variations, structure fighting the task — these are the architecture telling you something, not just noise to push through. Propose architectural changes when they'd make the code more sustainable. Frame as proposals with a clear ask ("now, or follow-up?"), not silent rewrites. ## Interpreting requests Treat vague input and question-back responses critically, not as instructions. - **Vagueness is not authorization.** "Make it cleaner", "maybe X?", "looks good but…" are signals to ask one clarifying question, not green lights to pick an interpretation and run. - **A tangent is not an answer.** If you ask "A or B?" and get "maybe X?", that's a new question, not a pick. Surface the mismatch and ask which the user meant — don't bundle the tangent into the active task as if it were direction. ## Team memory (cognee) cognee is a real memory, not an archive: unlike `MEMORY.md` it is **not** injected automatically, so it only works if you fetch from it and write to it on your own. The rules below are events, not attitudes — check them when the event happens, not "when it feels right". ### Read: `recall` before you start Run `recall` **before the first tool call**, not after you are already deep in the task, when any of these is true: - the task touches infrastructure, a server, a service, a ticket or a tool we run ourselves - an error looks like it could have happened before ("this smells familiar") - you are about to pick between options where a decision may already exist - the task will plausibly take more than a handful of tool calls `recall ` — no flags. It reads every readable dataset including the team one. `--team` exists on `remember` only; on `recall` it is a usage error, and `--dataset team-it` fails too because the team dataset is shared rather than owned (it would need its UUID). Neither is needed: plain `recall` covers everything. Treat what comes back like a colleague's note: useful, possibly outdated. If a memory names a file, flag or host, verify it still exists before acting on it. ### Write: `remember` at these moments Announce it in one line, never ask first. Write **as the insight appears**, not at the end of the session — by then the detail that made it worth saving is gone. - a bug is fixed and the cause was **not** visible in the code (config, limits, environment, an API that lies) - a decision is made and an alternative was rejected — save the *why*, that is what the code cannot tell later - a measurement contradicts an assumption, mine or yours - you correct me, or I correct myself after being wrong - a tool, API or service behaves differently than its docs claim What does **not** belong there: anything the repo already records, anything that only matters inside this one conversation, and never secrets, credentials or customer-personal data. ### Routing and hygiene - **Team bucket** (`remember --team`): everything concerning team IT — Seibert IT-Infra, ISAC/bw, monitoring, INFRA board, shared services, servers, team processes. Ask yourself: would a colleague hitting this next month benefit? - **Personal dataset** (plain `remember`): my preferences, workflow feedback, context that is only relevant to me. - On recurring topics `recall` first and **extend the existing note instead of adding a second one** — two notes on one topic are worse than none, because the older one keeps surfacing. - Write notes that answer a question, not headlines. Include the concrete numbers, the error message verbatim, and the fix. A note that says "there was a problem with X" costs more time than it saves. - No need to economize on characters: cognee has no size limit, so write notes comprehensively and self-contained. - Always keep the external references and source links in the note — they matter: Confluence, Jira, TeamVault, and, for notes that grew out of a Google Chat discussion, the source-thread URLs (`https://chat.google.com/room//`, for individual messages append the ``) so the original discussion stays traceable — not just a separate index. ## Sandbox - **Always run commands sandboxed first.** Only use `dangerouslyDisableSandbox: true` as a last resort after a sandbox-related failure — never preemptively. - **On sandbox failure:** analyze the error message for the blocked path, then suggest adding it to `sandbox.filesystem.allowWrite` in `~/.claude/settings.json`. Only fall back to `dangerouslyDisableSandbox: true` if the path can't be determined or the user prefers it. ## Temporary Files - **Use `$TMPDIR` or `.tmp/` (project-local) for temporary files.** Never use `/tmp` directly or paths like `/Library/Application Support` — those are not in the sandbox allowlist and trigger permission prompts. - `$TMPDIR` is set by the sandbox to a writable path. `.tmp/` inside the project directory is always writable without prompts. - Ensure `.tmp/` is listed in `.gitignore` when creating temp files in a tracked repo. ## Shell — literal `!` in Bash commands - **Never put a literal `!` in an inline Bash command.** Claude Code's Bash tool escapes every `!` to `\!` at the transport layer before any shell sees it — even inside single/double quotes and in non-interactive shells (anthropics/claude-code#61121, a regression of a fix shipped in 2.1.87). The stray backslash corrupts downstream tools: Python `!=` → SyntaxWarning + broken string, jq, Jira JQL (`status != Done` → server 400), branch names, etc. `bash -c '...'` and quoted heredocs do **not** avoid it. - **One rule covers everything:** if a command needs a `!`, write the command/code to a file with the Write tool under `.tmp/` and run the file. `.tmp/` is prompt-free via the `Edit(.tmp/**)` allow rule in `~/.claude/settings.json`. Do **not** create the file with inline `printf`/`echo >` — that re-escapes the `!`. - Need a literal `!` inline anyway: ANSI-C hex `$'\x21'` (e.g. `B=$'\x21'; cmd "${B}=…"`) yields a real `!` with no literal `!` in the command. ## Tooling - **Sourcebot MCP for org repos without a local checkout.** The `mcp__sourcebot__*` tools (instance sourcebot.it.seibert.diy) search the indexed Seibert codebases — Bitbucket DC/Cloud, Forgejo, seibert-external on GitHub. Reach for them when a question touches a repo that isn't cloned locally (other teams' code, cross-repo lookups, PR context): `grep`, `glob`, `read_file`, `list_tree`, `list_commits`, `get_diff`, `find_symbol_definitions`/`_references` answer in seconds and return file:line plus web links. A local checkout stays first choice when it exists. Never call `ask_codebase` on your own — it spawns a nested server-side agent (minutes per call, shared vLLM); use it only when explicitly asked. - **`ccc` for semantic code search.** Repos containing a `.cocoindex_code/` directory are indexed by [`ccc`](https://github.com/cocoindex-io/cocoindex-code). Reach for it on conceptual questions ("where is X used / which files do Y / what handles Z"), where a keyword grep would miss indirect usage: `ccc search ''`. Results are filtered to the current working directory's subtree, so **run the search from the project root** — that is the cheap way to see everything. `--path '**'` achieves the same from a subdirectory, but from the root it is a no-op *and* about three times slower (measured 2026-09-02 on a 1005-file index: 0.35 s against 0.12 s, identical hits), so pass it only when you cannot control the cwd. **Embeddings only, no keyword component:** searching an exact string (a UUID, a ticket ID, an error message) does not return the file that contains it — verified. `grep`/`rg`/`find` own exact-string lookups. A low score is a warning, not a hit. The `ccc` skill has the full reference. - **`ccc index` / `ccc init` are read-safe maintenance.** They only write to the gitignored `.cocoindex_code/` directory, never to source. Run them without confirmation prompts — at session start, after refactors, or before a search when the index may be stale. Treat like `grep` for permission purposes, not like a code edit. - **`md` für lange Markdown-Dateien statt `head`/`grep -n '^#'`.** Global auf dem PATH (`~/.local/bin/md` → `~/Projekte/ai/bin/md`). `md outline ` gibt den Überschriftenbaum mit Zeilennummer und Größe pro Abschnitt (`[164 Zeilen, ~2.1k Tok]`) — daraus die Lese-Entscheidung treffen, dann `md section "<Überschrift>"` für genau diesen Teilbaum (Query auch als Slug oder `L48`; `--range` liefert `offset limit` fürs Read-Tool, `--depth 0` schneidet Unterabschnitte ab). Der Parser kennt Code-Fences und Frontmatter, findet also kein `# Kommentar` aus einem ```bash-Block als Überschrift — der Grund, `grep` hier nicht zu nehmen. Bei Dateien unter ~500 Zeilen direkt `Read`, der Umweg lohnt erst darüber.