J-BlandandClaude Sonnet 5.5
d45d4bec97
Adds a marked global rules block, project AGENTS.md/CLAUDE.md template, an on-demand lean-review skill, a dry-run-first stdlib installer with backups, and tests using temp homes. README quick start no longer moves ~/.claude; legacy library stays opt-in. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
3.3 KiB
Lean setup
Default install is small: a marked rules block in the user-level instruction files, an optional lean-review skill for Claude, and a project template. The legacy library (.claude/, .agents/, .codex/) is untouched and stays opt-in.
Install
python3 scripts/lean-install.py global # dry-run: shows what would change
python3 scripts/lean-install.py global --apply # ~/.claude/CLAUDE.md, $CODEX_HOME/AGENTS.md, lean-review skill
python3 scripts/lean-install.py project /path/to/repo --apply # AGENTS.md + CLAUDE.md (@AGENTS.md)
python3 scripts/lean-install.py uninstall --apply # remove only the marked block
Options: --claude-home, --codex-home (defaults $CLAUDE_CONFIG_DIR/~/.claude, $CODEX_HOME/~/.codex), --skip-claude, --skip-codex, --skip-skill, --force.
Safety: dry-run unless --apply; the whole plan is validated before any write; an existing file is changed only by adding or replacing the marked block, after a *.bak-<timestamp> copy (never overwriting an earlier backup); symlinked targets, non-UTF-8 files, malformed markers and missing homes are refused; differing skill/project files need --force; settings, config.toml and auth.json are never read or written; no shell rc edits. Restore by copying a backup back over the file.
Codex reads $CODEX_HOME/AGENTS.override.md before AGENTS.md; an override file makes the installed global block inactive.
Optional full library
Copy pieces by hand rather than wholesale: pick agents from .claude/agents/ (or .codex/agents/), skills from .agents/skills/, and merge hook entries from .claude/settings.json into your own settings after backing yours up. Hooks there reference ~/.claude/hooks/, so only enable them once the scripts are copied there. Never replace ~/.claude or its credentials.
Sources and decisions
Official: Claude Code best practices, Codex AGENTS.md guide (redirects to learn.chatgpt.com/docs/agent-configuration/agents-md).
Comparison material: Migration Accelerator CLAUDE.md (public GitHub sample J-Bland/migration-accelerator; the private original on git.kinec.tech was unavailable, so this is a mirror and may differ) and HyperFactory AGENTS.md / diff-reviewer.
Adopted:
- Compact always-loaded files; detail on demand via skills and links (official; MA/HF both enforce a size budget).
- Verification the agent can run, reported with real output (Claude best practices).
- Explore/plan only for substantive changes (Claude best practices).
- One shared
AGENTS.md, withCLAUDE.mdimporting it via@AGENTS.md; global Codex file lives in the actualCODEX_HOME, project files layer root-down (Codex guide). - Evidence rule and one consolidated diff review: a finding needs a concrete failing input and a failed refutation, existing guards are checked first (HyperFactory diff-reviewer).
- Security review only when the diff warrants it.
Rejected: mandatory refactor agent after every green; stop-hook loops; full role inventories; xhigh/1M-context defaults; enabling every MCP or LSP plugin; broad global permissions; hooks pointing at paths that may not exist; multi-model review loops; changing model or provider settings.