mirror of https://github.com/coder/coder.git synced 2026-06-02 20:48:20 +00:00

Files

T

Matt Vollmer 5612bb81cb docs(docs/ai-coder): replace Coder Tasks references with Coder Agents (#24929 )

Updates `docs/ai-coder/index.md`, `docs/ai-coder/best-practices.md`, and
`docs/ai-coder/ai-governance.md` to point readers at Coder Agents and
the AI Governance Add-On instead of Coder Tasks and Agent Firewall
(CODAGT-157).

## Changes

- `docs/ai-coder/index.md`:
- Rename `## Agents with Coder Tasks` to `## Coder Agents`. Drop the
Devin / ChatGPT Codex name-drops and the Tasks pitch. New copy points at
`./agents/index.md`, names the agent loop in the control plane, and
notes that workspaces can be completely network isolated. Image swapped
from `tasks-ui.png` to `agents-hero-image.png` (the hero shot added in
#24915).
- Replace the `## Secure Your Workflows with Agent Firewall` section
with `## Govern AI activity with the AI Governance Add-On`. The new
section opens with adoption-first framing (visibility, guardrails, cost)
and links to `./ai-governance.md`, with bulleted callouts for AI
Gateway, Agent Firewall, and the expanded Agent Workspace Build
allowance the add-on bundles.
- `docs/ai-coder/best-practices.md`:
- In the use-case table, swap `[Tasks](./tasks.md)` to `[Coder
Agents](./agents/index.md)` for the developer-led-investigation and
prototyping rows, and swap the "Tasks API *(in development)*" cell to
`[Coder Agents API](./agents/chats-api.md)` for the background-jobs row.
Retitle the Security section link from "securing agents with Coder
Tasks" to "securing AI agents" since `security.md` does not actually
mention Tasks. Re-ran `markdown-table-formatter` to repad column widths.
- In `## Provide Agents with Proper Context`, add a paragraph describing
how context is provided in Coder Agents (admin-configured system
prompts, centrally registered MCP servers, and skills shipped from repos
or templates under `.agents/skills/`), with a transition line clarifying
that the existing Memory and Tools subsections cover BYO-agent patterns.
- `docs/ai-coder/ai-governance.md`: drop the "Additional Tasks Use (via
Agent Workspace Builds)" bullet from the intro feature list and the
"Expanding the use of Coder Tasks for AI-driven background work" bullet
from the audience list. The `## How Coder Tasks usage is measured`
section and the rest of the Tasks-related prose on this page are
intentionally left for a follow-up PR.

## Notes for the reviewer

- The `[Coder Agents API](./agents/chats-api.md)` link in
`best-practices.md` will need to be retargeted if #24830 (which replaces
`agents/chats-api.md` with auto-generated `reference/api/chats.md`)
lands first.
- This is the first slice of the Tasks-references audit. Remaining files
(`tasks-core-principles.md`, `tasks-lifecycle.md`, `tasks-migration.md`,
`cli.md`, `github-to-tasks.md`, `agent-compatibility.md`, the rest of
`ai-governance.md`, `custom-agents.md`,
`ai-gateway/clients/claude-code.md`, `manifest.json`,
`reference/api/tasks.md`, the `task*` CLI references, the ESR upgrade
guide, `feature-stages.md`, `workspace-scheduling.md`,
`shared-workspaces.md`) will land in follow-up PRs against the same
Linear ticket. Open PRs #24831, #24833, and #24841 cover separate slices
and do not touch any file in this PR.
- Validation: `markdownlint-cli2`, `markdown-table-formatter`,
`scripts/check_emdash.sh`, and `make pre-commit-light` all pass.

PR generated with Coder Agents.

2026-05-04 13:00:39 -04:00

5.9 KiB

Raw Blame History

Best Practices

This document includes a mix of cultural and technical best practices and guidelines for introducing AI agents into your organization.

Identify Use Cases

To successfully implement AI coding agents, identify 3-5 practical use cases where AI tools can deliver real value. Additionally, find a target group of developers and projects that are the best candidates for each specific use case.

Below are common scenarios where AI coding agents provide the most impact, along with the right tools for each use case:

Scenario	Description	Examples	Tools
Automating actions in the IDE	Supplement tedious development with agents	Small refactors, generating unit tests, writing inline documentation, code search and navigation	IDE Agents in Workspaces
Developer-led investigation and setup	Developers delegate research and initial implementation to AI, then take over in their preferred IDE to complete the work	Bug triage and analysis, exploring technical approaches, understanding legacy code, creating starter implementations	Coder Agents, to a full IDE with Workspaces
Prototyping & Business Applications	User-friendly interface for engineers and non-technical users to build and prototype within new or existing codebases	Creating dashboards, building simple web apps, data analysis workflows, proof-of-concept development	Coder Agents
Full background jobs & long-running agents	Agents that run independently without user interaction for extended periods of time	Automated code reviews, scheduled data processing, continuous integration tasks, monitoring and alerting	Coder Agents API
External agents and chat clients	External AI agents and chat clients that need access to Coder workspaces for development environments and code sandboxing	ChatGPT, Claude Desktop, custom enterprise agents running tests, performing development tasks, code analysis	MCP Server

Provide Agents with Proper Context

While LLMs are trained on general knowledge, it's important to provide additional context to help agents understand your codebase and organization.

For Coder Agents, context comes from a few complementary places. Platform admins configure a system prompt that applies to every chat and register MCP servers once for the whole deployment. Repos and workspace templates can ship reusable skills under .agents/skills/, which the agent discovers automatically when it attaches to the workspace. Developers don't need to manage memory files or wire up tools themselves.

The rest of this section covers patterns for agents you run yourself inside a workspace, such as Claude Code or Codex.

Memory

Coding Agents like Claude Code often refer to a memory file in order to gain context about your repository or organization.

Look up the docs for the specific agent you're using to learn more about how to provide context to your agents.

Tools (Model Context Protocol)

Agents can also use tools, often via Model Context Protocol to look up information or perform actions. A common example would be fetching style guidelines from an internal wiki, or looking up the documentation for a service within your catalog.

Look up the docs for the specific agent you're using to learn more about how to provide tools to your agents.

Our Favorite MCP Servers

In internal testing, we have seen significant improvements in agent performance when these tools are added via MCP.

Playwright: Instruct your agent to open a browser, and check its work by viewing output and taking screenshots.
desktop-commander: Instruct your agent to run long-running tasks (e.g. npm run dev) in the background instead of blocking the main thread.

Security & Permissions

LLMs and agents can be dangerous if not run with proper boundaries. Be sure not to give agents full permissions on behalf of a user, and instead use separate identities with limited scope whenever interacting autonomously.

Learn more about securing AI agents

Keep it Simple

Today's LLMs and AI agents are not going to refactor entire codebases with production-grade code on their own! Using coding agents can be extremely fun and productive, but it is important to keep the scope of your use cases small and simple, and grow them over time.

5.9 KiB Raw Blame History