
drift
Learned conventions for Claude Code: rules before writing, advice after editing, and a block at the end of the turn for conventions you set to block.
- GitHub stars
- 795
Install
/plugin install drift@driftRun it inside Claude Code after adding the marketplace with /plugin marketplace add dadbodgeoff/drift.
Contents
Discovered from sourceSkills 1
Working with Drift
Drift reads this repository's code and answers, as facts, how it is built: its
packages, entry points, the guards they carry, and what is not known. Where a
.drift/conventions.yaml exists, it also holds conventions learned from the code
and approved by its maintainers.
- Before reading sibling files to learn how a route, handler, job or component
is built here, run
drift card <path>(works for a file that does not exist yet). Read other files only for what it lists under Not known. It is one cheap call (MCPdrift_card): the file's package, its entry points with their guards, what its siblings carry with a file to copy, and a last line, "Not known: ...". When it says "No answer for this file", read or grep as usual.drift mapgives the packages, layers and entry points of the whole repository. - Before searching for how this codebase handles auth, validation, errors,
routes or data access, or for its structure (packages, entry points, a file's
role), run
drift card <target file>(ordrift practices --path <file>when available). Grep only for what it reports as not known. Keep using grep to find where a symbol is called or a string is defined. These lookups are read-only and run without a permission prompt.
In a repository with .drift/conventions.yaml:
- Before creating a file, run
drift example <path>and copy the structure of the file it names: its wrappers, guards and imports. For a path that does not exist yet, the examples are grouped by what the file will contain ("if it exports HTTP handlers"); follow the group that matches what you are writing. - When Drift reports a violation, read whether it blocks. One marked
(blocks)(ormode blockindrift check) must be fixed to match the convention, unless the exception is intentional. Everything else is advice: follow it where it fits the code at hand; where it does not fit, no action is needed: no change and no comment. Each report shows the rule, why (how many members of its role follow it), its known exceptions ("except ...") and an example to copy;drift_explain <id>says more. - If a blocking finding is an intentional exception, add
// drift-ignore <id>: <reason>(# drift-ignore <id>: <reason>in Python) directly above the declaration. A comment without a reason does not suppress anything. Reviewers see every suppression, so give a real reason. Advice never needs one. - If Drift says suggestions are hidden until verified (experimental), you
may verify one with the MCP tool
drift_verify_card: run its prompt 3 times in fresh contexts and send the replies back. It is optional. - Never edit
.drift/conventions.yamlordrift.lock. People change policy withdrift review; edits by agents are denied. - When adding an endpoint, job or client component, run
drift security <files>to see the guards, risky operations (raw SQL, shell, raw HTML, computed redirects) and server-only imports it reaches. These are facts for you to judge, not rules; mention anything new in your summary. - Run
drift checkbefore finishing to see any remaining new violations. Legacy code is baselined, so only new problems are listed. A violation of a convention in block mode (marked(blocks)in Drift's hook messages andmode blockindrift check) fails the check and stops the end of your turn; the others, suggestions included, are advice, and need no action where they do not fit.
MCP servers 1
Sponsors
Details
- Marketplace
- dadbodgeoff/drift
- Source
- integrations/claude-code
- Category
- Community