coder · bpmct · Jul 7, 2025 · Jun 30, 2025 · Jun 30, 2025 · Jun 30, 2025
diff --git a/docs/ai-coder/agents.md b/docs/ai-coder/agents.md
diff --git a/docs/ai-coder/best-practices.md b/docs/ai-coder/best-practices.md
@@ -1,71 +1,53 @@
-# Model Context Protocols (MCP) and adding AI tools
+# Best Practices
 
-> [!NOTE]
->
-> This functionality is in beta and is evolving rapidly.
->
-> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
-> Always review AI-generated content before using it in critical systems.
->
-> Join our [Discord channel](https://discord.gg/coder) or
-> [contact us](https://coder.com/contact) to get help or share feedback.
+This document includes a mix of cultural and technical best practices and guidelines for introducing AI agents into your organization.
 
-## Overview
+## Identify Use Cases
 
-Coder templates should be pre-equipped with the tools and dependencies needed
-for development. With AI Agents, this is no exception.
+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.
 
-## Prerequisites
+Below are common scenarios where AI coding agents provide the most impact, along with the right tools for each use case:
 
-- A Coder deployment with v2.21 or later
-- A [template configured for AI agents](./create-template.md)
+| 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](./ide-agents.md) 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 | [Tasks](./tasks.md), to a full IDE with [Workspaces](../user-guides/workspace-access/index.md) |
+| **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                 | [Tasks](./tasks.md)                                                                            |
+| **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             | [Tasks](./tasks.md) API *(in development)*                                                     |
+| **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](./mcp-server.md)                                                                  |
 
-## Best Practices
+## Provide Agents with Proper Context
 
-- Use the most capable ML models you have access to in order to evaluate Agent
-  performance.
-- Set a system prompt with the `AI_SYSTEM_PROMPT` environment in your template
-- Within your repositories, write a `.cursorrules`, `CLAUDE.md` or similar file
-  to guide the agent's behavior.
-- To read issue descriptions or pull request comments, install the proper CLI
-  (e.g. `gh`) in your image/template.
-- Ensure your [template](./create-template.md) is truly pre-configured for
-  development without manual intervention (e.g. repos are cloned, dependencies
-  are built, secrets are added/mocked, etc.).
+While LLMs are trained on general knowledge, it's important to provide additional context to help agents understand your codebase and organization.
 
-  > Note: [External authentication](../admin/external-auth/index.md) can be helpful
-  > to authenticate with third-party services such as GitHub or JFrog.
+### Memory
 
-- Give your agent the proper tools via MCP to interact with your codebase and
-  related services.
-- Read our recommendations on [securing agents](./securing.md) to avoid
-  surprises.
+Coding Agents like Claude Code often refer to a [memory file](https://docs.anthropic.com/en/docs/claude-code/memory) in order to gain context about your repository or organization.
 
-## Adding Tools via MCP
+Look up the docs for the specific agent you're using to learn more about how to provide context to your agents.
 
-Model Context Protocol (MCP) is an emerging standard for adding tools to your
-agents.
+### Tools (Model Context Protocol)
 
-Follow the documentation for your [agent](./agents.md) to learn how to configure
-MCP servers. See
-[modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)
-to browse open source MCP servers.
+Agents can also use tools, often via [Model Context Protocol](https://modelcontextprotocol.io/introduction) 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.
 
-### Our Favorite MCP Servers
+Look up the docs for the specific agent you're using to learn more about how to provide tools to your agents.
 
-In internal testing, we have seen significant improvements in agent performance
-when these tools are added via MCP.
+#### Our Favorite MCP Servers
+
+In internal testing, we have seen significant improvements in agent performance when these tools are added via MCP.
 
 - [Playwright](https://github.com/microsoft/playwright-mcp): Instruct your agent
   to open a browser, and check its work by viewing output and taking
   screenshots.
 - [desktop-commander](https://github.com/wonderwhy-er/DesktopCommanderMCP):
-  Instruct your agent to run long-running tasks (e.g. `npm run dev`) in the
-  background instead of blocking the main thread.
+  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 agents with Coder Tasks](./security.md)
 
-## Next Steps
+## Keep it Simple
 
-- [Supervise Agents in the UI](./coder-dashboard.md)
-- [Supervise Agents in the IDE](./ide-integration.md)
-- [Supervise Agents Programmatically](./headless.md)
-- [Securing Agents](./securing.md)
+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.
diff --git a/docs/ai-coder/coder-dashboard.md b/docs/ai-coder/coder-dashboard.md
diff --git a/docs/ai-coder/create-template.md b/docs/ai-coder/create-template.md
diff --git a/docs/ai-coder/custom-agents.md b/docs/ai-coder/custom-agents.md
@@ -1,21 +1,11 @@
 # Custom Agents
 
-> [!NOTE]
->
-> This functionality is in beta and is evolving rapidly.
->
-> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
-> Always review AI-generated content before using it in critical systems.
->
-> Join our [Discord channel](https://discord.gg/coder) or
-> [contact us](https://coder.com/contact) to get help or share feedback.
-
-Custom agents beyond the ones listed in the [Coder registry](https://registry.coder.com/modules?tag=agent) can be used with Coder.
+Custom agents beyond the ones listed in the [Coder registry](https://registry.coder.com/modules?tag=agent) can be used with Coder Tasks.
 
 ## Prerequisites
 
 - A Coder deployment with v2.21 or later
-- A [Coder workspace / template](./create-template.md)
+- A [Coder workspace / template](../admin/templates/creating-templates.md)
 - A custom agent that supports Model Context Protocol (MCP)
 
 ## Getting Started
@@ -31,19 +21,18 @@ From there, the agent can run the MCP server with the `coder exp mcp server` com
 Inside a Coder workspace, run the following commands:
 
 ```sh
-coder login # be sure to be authenticated with the Coder CLI
-export CODER_MCP_APP_STATUS_SLUG=my-agent # needs to be the same as the slug in the coder_app resource
+coder login
+export CODER_MCP_APP_STATUS_SLUG=my-agent
 
 # Use your own agent's logic and syntax here:
 any-custom-agent configure-mcp --name "coder" --command "coder exp mcp server"
 ```
 
 This will start the MCP server and report activity back to the Coder control plane on behalf of the coder_app resource.
 
-> See the [Goose module](https://github.com/coder/registry/blob/main/registry/coder/modules/goose/main.tf) source code for a real world example.
+> [!NOTE]
+> See [this version of the Goose module](https://github.com/coder/registry/blob/release/coder/goose/v1.3.0/registry/coder/modules/goose/main.tf) source code for a real world example.
 
 ## Contributing
 
-We welcome contributions for various agents via the [Coder registry](https://registry.coder.com/modules?tag=agent)!
-
-See our [contributing guide](https://github.com/coder/registry/blob/main/CONTRIBUTING.md) for more information.
+We welcome contributions for various agents via the [Coder registry](https://registry.coder.com/modules?tag=agent)! See our [contributing guide](https://github.com/coder/registry/blob/main/CONTRIBUTING.md) for more information.