Files
coder/docs/ai-coder/best-practices.md
T
Nick Vigilante bc77c40296 docs: add front-matter titles to mechanical and no-H1 pages (Phase 3) (#28030)
## Summary

**Batch A of Phase 3** of the H1 → front-matter migration (`DOCS-484`;
parent `DOCS-477`). Adds a front-matter `title` to every navigable docs
page whose title can be migrated **mechanically**, with no editorial
judgment.

This is the content step that Phase 1 (renderers prefer front-matter
title, `DOCS-482`) and Phase 2 (tooling + generators front-matter-aware,
`DOCS-483`) unblocked. Both are merged; coder.com #964/#974 are merged
and live.

**Rendered no-op.** The renderers already resolve the page title from
the manifest and hide the leading body H1 (Phase 1), so no page changes
visually. This just moves the title into front matter where Fumadocs and
the migrated tooling can read it.

## What's in this batch

Dry-run on `main` (464 navigable pages) splits into:

| category | count | this PR |
|----------|-------|---------|
| already has front-matter title (Reference, from Phase 2 generators) |
196 | skipped (idempotent) |
| **mechanical** — leading body H1 equals the manifest label | 138 | ✅
add front-matter `title`, drop the duplicate H1 |
| **no body H1** — renders under the manifest label only | 4 | ✅ add
front-matter `title` only |
| **mismatch** — body H1 differs from the manifest label | 126 | ⏭️
deferred (needs an editorial decision, see below) |

142 files changed, all under `docs/`.

## Deliberately out of scope: the 126 mismatches

Pages where the body H1 is richer than the short sidebar label (e.g.
label **Modules** / H1 *Contributing modules*, label **Install** / H1
*Installing Coder*) need a canonical-title decision, not a script. A few
even look like the body H1 is the redundant one (`install/cli.md` and
`install/index.md` both carry the H1 *Installing Coder*). These will
land in follow-up batches **by nav section** once the policy is set, so
each gets real review.

## Verification

AI was the primary author of this PR (see disclosure below); per the [AI
Contribution
Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING)
here is the manual verification.

- Every added front-matter block parses as YAML and its `title`
round-trips to the manifest label (checked programmatically across all
142 files).
- Every removed line is a leading `# H1` that equalled the manifest
title; no body prose was reflowed. Front matter is correctly hoisted
above pre-existing `<!-- markdownlint-disable -->` comments on the two
pages that had them.
- `pnpm check-docs` (markdownlint-cli2 + table formatter) passes on the
changed set: `Summary: 0 error(s)`. `MD041` stays off (re-enabled in
Phase 4); `MD025` is not tripped because the duplicate body H1s are
removed.

```
$ pnpm exec markdownlint-cli2 $(git diff --name-only origin/main)
Linting: 142 file(s)
Summary: 0 error(s)
```

Linear: DOCS-484

> This PR was created with AI assistance (Coder Agents).
2026-08-27 12:34:13 -04:00

6.0 KiB

title
title
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 per organization. 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 the Agent Firewall

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.