CLAUDE.md, AGENTS.md and Venom
Rules files hold what rarely changes and travels with the code. Venom holds work in progress, shared skills and tools.
Keep your CLAUDE.md and AGENTS.md, and use Venom beside them. Rules files hold rules that rarely change and travel with the code. Venom holds work in progress, shared skills and tools across repositories and across different agents. They solve different problems, so you don't have to choose.
What goes where?
| Rules files in the repo | Venom | |
|---|---|---|
| Holds | Conventions that rarely change: build commands, code style, project layout. | Tasks, decisions, status, artifacts, shared skills and connected tools. |
| Changes | When the code or its rules change, through a commit. | As work progresses, through task logs and published revisions. |
| Travels with | The repository. | The project in your organization. |
| Read by | The agent that loads that file. | Any connected agent, through MCP. |
| Spans | One repository. | Several repositories and different agents. |
Why keep your rules files?
A rules file is versioned with the code it describes. It is reviewed in a pull request, and every clone has it. That is the right home for facts about how to build and test a repository.
Venom doesn't replace that. It covers what a file in one repository can't: what Jordan decided yesterday, what Sam's agent found in review, which task is blocked, and what to do next.
What belongs in Venom instead?
- Work in progress. A task holds the brief, the log and the status, so a different person's agent can continue.
- Shared practices. A skill published to a project, team or organization is read from Venom. People don't need to copy it into local agent configs.
- Shared tools. Teams add MCP servers once, and Venom passes their tools through the same connection.
- Work that spans agents. One teammate may use Claude Code and another Cursor. Both read the same task.
How do they work together?
A rules file can tell the agent how this repository builds. The Venom connection tells it where the team's work stands. Venom's server instructions tell connected agents to read the project and task before acting and to log decisions, outcomes and next steps.
Venom doesn't edit these files. For some clients, setup asks you to add a few lines of Venom guidance to a rules file. The rest stays as you maintain it today.