prefer-local-over-global-edits

Prefer Local Over Global — Edit Project `.claude/`, Not `$HOME/.claude/`

Rule

When asked to update, edit, fix, or extend a rule, skill, agent, hook, or any registry fragment, default to the project-local copy under ./.claude/ — NOT the global copy under $HOME/.claude/.

Override only when the user explicitly uses trigger words: “global”, “user-level”, “user-scope”, “$HOME/.claude”, ”~/.claude”, “for me only”, “just on my machine”, “personal”.

If none of those appear, the default is local.

How to apply

Default target = ./.claude/<area>/<file>. Never silently edit $HOME/.claude/ when a project-local exists or could exist.
If only the global copy exists, AskUserQuestion: copy-local-and-edit (default), edit-global-only, or open the owning kit repo.
Kit source repos: edit project-local; CI propagates. Consumer repos: edit project-local; recommend /t1k:sync-back to upstream.
Readback direction (sync-back): t1k-sync-back walks ./.claude/ FIRST and $HOME/.claude/ SECOND — project-local is canonical on both the write (edit) AND read (sync-back) sides.

Gotcha — Updates CAN clobber divergent local edits (#367)

t1k modules update extracts the release ZIP without diffing per-file content, so a project-local .claude/ file that has diverged ahead of the kit (edited locally, never synced back) WILL be overwritten. Run /t1k:sync-back FIRST, let the kit re-release, then update.

Narrow exceptions: override ONLY when the user uses an explicit global trigger word, the change is user-personal (keybindings, MCP config, memory), or the file only exists in $HOME/.claude/ by design. When in doubt, AskUserQuestion.

Anti-patterns and the full exception rationale: docs/prefer-local-over-global-edits.md.

orchestration-rules.md · agents/t1k-kit-developer.md § “Module Registry Sync” · CLAUDE.md Core Requirement #5 (settings path scope) + #11 (default goal is ship)