Files

Paul O'Reilly a4967df815 Initial commit: Claude Code foundations and improvements research

Conventions, community best practices research (Sept 2025 - March 2026),
and prioritized improvement backlog for Claude Code workflows.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-12 23:02:54 +13:00

1.8 KiB

Raw Blame History

Global Configuration

Why This Matters

A global ~/.claude/CLAUDE.md provides cross-project defaults, eliminating duplication across project-level files. The community has converged on a layered configuration strategy.

Current State

No global ~/.claude/CLAUDE.md exists
Cross-project conventions (Gitea, secrets, SSH) are in the project-level ~/dev/claude/CLAUDE.md
~/.claude/settings.json contains only {"model": "opus"}

Layered Configuration Model

Layer	File	Scope	Checked In
Personal defaults	`~/.claude/CLAUDE.md`	All projects	No
Project shared	`./CLAUDE.md`	Team, per-project	Yes
Directory-specific	`./subdir/CLAUDE.md`	Loaded when working in subdir	Yes
Local overrides	`CLAUDE.local.md`	Machine-specific, gitignored	No
Path-scoped rules	`.claude/rules/*.md`	Conditional on file patterns	Yes
On-demand knowledge	`.claude/skills/*/SKILL.md`	Loaded only when relevant	Optional

Suggested Global CLAUDE.md Content

Move these from the project-level file to global:

Gitea conventions — SSH aliases, remote URL format, org structure
Secrets folder rules — read-only, never copy values, never pass as CLI args
Commit message format — meaningful messages, small focused commits
Session behaviour — "Do not allow implicit decisions — confirm with the user"
Response style — concise, no trailing summaries, no unnecessary emojis
SOPS + age as the standard encryption tool
Documentation standards that apply across all projects (CLAUDE.md, MEMORY.md, FUTURE.md, README.md)

Settings.json Improvements

Beyond model, consider:

Hook definitions (see hooks-and-automation.md)
MCP server registrations (see mcp-servers.md)
Permission preferences for common tool calls

1.8 KiB Raw Blame History