Selvedge project instructions for AI coding agents

Use project instructions to ask your coding agent to check prior decisions before editing, record why it changed code, and save rejected approaches with their reasons. Selvedge supplies the tools and this instruction block; a connected server or a saved instruction does not guarantee that the agent follows it.

Install for your editor

Run selvedge setup from your project after installing Selvedge to detect supported setup presets. For any compatible agent, selvedge prompt prints the block to add to its project instructions. selvedge prompt --install PATH updates the actual instruction file your client reads. See manual MCP or CLI setup when your agent has no preset.

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 a stable name for the agent or tool making the change.
- 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. Where a compatible edit-gate hook is
  installed and active, watched edits require this lookup. Hook capabilities
  and activation depend on the client.
- A reverted decision is not a permanent ban. If the constraint that
  killed it no longer holds, re-open it explicitly with
  `change_type="supersede"` (never re-apply a reverted change without
  superseding it first).
- Log abandoned paths too: use `change_type="reject"` when you considered
  an approach and decided against it without writing it, and
  `change_type="revert"` when you rolled a change back — ideally with
  `stale_when` or `expires_when` naming the condition that would
  invalidate the verdict, so `stale_decisions` can surface it later.
- 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, revert, reject, supersede; for a
  rename add `--rename-from <old>`).
- Re-open a reverted decision: `selvedge supersede <entity> --reasoning "<why>"`.
- 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

These are the requested behaviors to verify:

• Before editing, retrieve the relevant entity’s history and assess whether recorded constraints still apply. The mistake-prevention rule shows a concise instruction and a worked example.
• After a change, record the stated reason and outcome. Use a shared changeset identifier to group related events across entities.
• After declining an approach, record a reject with the reason and a condition for review. Use revert for an implemented approach that was rolled back.

Verify the instructions in a new session

1. Ask your agent to record one real decision with an entity path and a useful reason.
2. End that session and start a new one in the same project, using the same database.
3. Ask it to retrieve the decision before editing that entity. Inspect both the tool result and the agent’s plan.

If the record is missing, check the database location, entity path and whether logging actually happened. If it is found but ignored, review the agent’s instructions and tool use. Applicable native lifecycle hooks can gate selected edits; the instruction block alone does not enforce them in every client. The agent memory guide explains persistence and retrieval, and the concepts hub defines the terms used here.

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