Deep Agents Agent Rules

An agent framework and monorepo for planning, coding agents, tools, and partner integrations.

Overview

Deep Agents keeps shared constraints at the root and moves architecture, development, releases, and package work to focused guides. The root rules cover warning filters, API compatibility, repository searches, and generated reference material.

Behavioral framing Hard prohibitions Pointing at the source of truth Context budgeting

Documents

├── 
├── .github
│   ├── 
│   ├── 
│   └── 
├── examples
│   ├── content-builder-agent
│   │   └── 
│   ├── deploy-coding-agent
│   │   └── 
│   ├── deploy-content-writer
│   │   ├── user
│   │   │   └── 
│   │   └── 
│   ├── deploy-gtm-agent
│   │   ├── subagents
│   │   │   └── market-researcher
│   │   │       └── 
│   │   └── 
│   ├── deploy-mcp-docs-agent
│   │   └── 
│   ├── nvidia_deep_agent
│   │   └── src
│   │       └── 
│   ├── talon
│   │   └── 
│   └── text-to-sql-agent
│       └── 
└── libs
    ├── code
    │   ├── 
    │   └── 
    ├── evals
    │   └── 
    ├── partners
    │   └── 
    ├── 
    └──

Techniques in this file

01 / Behavioral framing

Reject tests that only freeze implementation shape

Tests must assert visible behavior, not incidental call order. A refactor that preserves behavior should not require mechanical test changes.

83- Test observable behavior rather than duplicating implementation logic. Do not add change-detector tests that merely restate the current code structure or assert incidental interactions, such as internal call order, without proving meaningful behavior. Refactors that preserve behavior should not require mechanical test updates; rewrite or remove tests that do. Cover edge cases and keep tests deterministic.

02 / Hard prohibitions

Match suppression scope to the actual exception

A single Ruff violation gets an inline suppression with a reason; file-wide ignores are reserved for categorical policies. The rule makes unjustified suppression a signal to reconsider the code.

26Use inline `# noqa: RULE` with a justification for individual exceptions. Reserve `[tool.ruff.lint.per-file-ignores]` for categorical policies that apply to a whole class of files, such as tests not requiring docstrings. Do not hide a single violation with a file-wide ignore. If you cannot justify a suppression, the code is probably the problem. See [`libs/DEVELOPMENT.md`](libs/DEVELOPMENT.md#suppressing-ruff-rules) for worked examples.

03 / Pointing at the source of truth

Keep generated context below source evidence

The optional OpenWiki index is available just in time, but its unknowns are not new requirements. Source and tests remain authoritative, and normal updates happen by changing those inputs.

149- Treat source code and tests as authoritative. A brief's unknowns and review items are verification gaps, not automatic requirements.

04 / Context budgeting

Constrain searches to the relevant package

The routing section names SDK, coding-agent, ACP, eval, and partner paths while excluding environments and generated trees. Dependency searches start from the exact environment file.

118Exclude package `.venv` directories, hidden worktrees, `deepagents.egg-info`, generated metadata, benchmark results, and scratch files unless needed. For dependency internals, find the exact environment file instead of searching all of `site-packages`.

Preserve anchors that other configuration depends on

The warnings section is not only prose: package configuration comments refer to its heading. The guide explicitly asks editors to keep that name stable.