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]>
38 lines
3.3 KiB
Markdown
38 lines
3.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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](https://code.claude.com/docs/en/best-practices), [Codex AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md) (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`, with `CLAUDE.md` importing it via `@AGENTS.md`; global Codex file lives in the actual `CODEX_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.
|