pal-e-docs

SOP: Claude Config Development

sop-claude-config-development Sop

sop active
Project

SOP: Claude Config Development

How to develop the claude-custom repo safely. This repo is symlinked as ~/.claude/, which means every file change is live in production. Standard branch discipline applies, but testing requires a symlink swap.

The Problem

~/.claude/ is a symlink to ~/claude-custom-forgejo/ (the repo's main working tree). Changes to hooks, skills, settings, or commands take effect immediately — no deploy step, no review gate. This is powerful but dangerous. Without discipline, changes accumulate uncommitted on whatever branch is checked out.

Chicken-and-Egg

Enforcement hooks live in this repo. You can't use hooks to enforce changes to the hooks themselves. This means:
  • Some PreToolUse guards won't fire when editing the repo they live in
  • QA review is extra important here — it's the primary enforcement mechanism
  • The development SOP must be followed by convention, not enforced by hooks

Workflow

  • Create issue — same as any other repo. Use Issue Creator agent or create manually.
  • Create worktree — git worktree add .worktrees/{issue-number}-{description} -b {issue-number}-{description}
  • Develop in the worktree — edit hooks, skills, settings, commands in .worktrees/{branch}/. Production (~/.claude/) stays on main, unaffected.
  • Test: swap the symlink — 
    # Point ~/.claude/ at the worktree for testing
ln -sfn ~/claude-custom-forgejo/.worktrees/{branch} ~/.claude

# Run claude, spawn test agents, verify hooks fire correctly

# Restore production
ln -sfn ~/claude-custom-forgejo ~/.claude
  • Submit PR — push branch, open PR on Forgejo.
  • QA review — extra scrutiny here. QA agent checks SOP compliance + correctness. Since hooks can't self-enforce, review is the primary gate.
  • Merge — after approval. Production picks up changes via the symlink automatically.
  • Clean up worktree — git worktree remove .worktrees/{branch}

.gitignore

The following should be in .gitignore to prevent artifact drift:

Branch Discipline

  • Never develop directly on main — main is production via the symlink
  • Always use worktrees for isolation
  • Always push before switching worktrees
  • Never leave uncommitted changes on main
  • Clean up stale branches and worktrees regularly

What's Different From Other Repos

Normal repo claude-custom
Changes deploy via CI/CD Changes are live immediately via symlink
Hooks enforce SOP Hooks can't enforce changes to themselves
Test in CI Test via symlink swap
Merge is safe Merge immediately affects all Claude sessions
  • worktree-workflow — the general worktree SOP
  • solo-dev-pr-workflow — PR flow (same as other repos)
  • project-claude-config — project page