The Selvedge agent prompt block

Paste this into your project’s CLAUDE.md, .cursorrules, or copilot-instructions.md. It tells your AI coding agent two things: call prior_attempts before editing an entity (so it doesn’t repeat a change the team already reverted), and log why it changed code the moment it does.

One block, two new habits

Your agent now checks its own history before it writes, and leaves a durable trail of why behind every change. pip install selvedge first, then drop this in. Or just run selvedge prompt --install CLAUDE.md and Selvedge installs (and keeps it updated) for you.

Copy this

The code block below has a one-click Copy button in its top-right corner — hover it and click.

<!-- selvedge:start -->
## Selvedge — change tracking

You have access to Selvedge (MCP server: `selvedge`) for change tracking.

**Rules:**

- Call `selvedge.log_change` immediately after adding, modifying, or
  removing any DB column, table, function, API endpoint, dependency,
  or env variable.
- Set `reasoning` to the user's original request or the problem being
  solved. Write at least one full sentence — the server will warn on
  empty, very short, or generic values like "user request" or "done".
  Good example: "User asked to add 2FA — needs phone number to send
  SMS verification codes."
- Set `agent` to "claude-code" (or whichever agent you are).
- Set `session_id` if you have access to the current session/conversation ID.
- Set `git_commit` to the commit hash once you know it.
- For multi-entity changes (e.g. adding a whole feature), set a shared
  `changeset_id` on all related `log_change` calls — use a short slug
  like `add-stripe-billing`. This lets anyone query the full scope of
  the change with `selvedge.changeset()`.
- Before editing an entity, call `selvedge.prior_attempts` on it — if the
  same change was tried before and reverted, you'll see the prior
  reasoning and why it was rejected, and can change your plan instead of
  repeating a rejected approach.
- Then call `selvedge.diff` or `selvedge.blame` for the entity's broader
  history before conflicting with past decisions.

**The same operations are on your shell.** Selvedge is MCP-first, but the
identical local store is also a CLI (`selvedge` is on your PATH after
install). When the MCP server isn't loaded, you're in a shell-only subagent,
or you just want to keep context light, use the equivalents:

- Check an entity first: `selvedge prior-attempts <entity>` (was it tried and
  reverted before?), then `selvedge blame <entity>` / `selvedge diff <entity>`
  for its broader history.
- Log a change: `selvedge log <entity> <change_type> --reasoning "<why>"`
  (change_type: add, remove, modify, rename, retype, create, delete,
  index_add, index_remove, migrate; for a rename add `--rename-from <old>`).
- Find things: `selvedge search "<query>"`, `selvedge history --since 7d`,
  `selvedge stale` (decisions now due for a revisit).

Add `--json` to any read command; `selvedge <command> --help` gives detail on
demand.
<!-- selvedge:end -->

Why the sentinels

The <!-- selvedge:start --> / <!-- selvedge:end --> markers let selvedge prompt --install <file> update the block in place on future releases without disturbing anything else in your file. Install it once by hand, or let the CLI own it:

pip install selvedge
selvedge prompt --install CLAUDE.md   # idempotent; writes a .bak first

What your agent does with it

• Before editing users.card_token, the agent calls prior_attempts and learns it was added and reverted 28 days ago (“storing card tokens pulled us into PCI-DSS scope — moved to Stripe-managed methods”). It changes its plan instead of repeating the mistake.
• After changing anything structural, it logs the why in its own words — so six months later, selvedge blame answers the question git blame can’t.

Full docs: selvedge.sh · pip install selvedge · GitHub