From d1a713aa26c91897aca45cb09e237496724e0c54 Mon Sep 17 00:00:00 2001 From: Trevor Elkins Date: Tue, 27 Jan 2026 10:50:17 -0500 Subject: [PATCH 1/7] feat(ai): add dev docs for agent use --- .../ai-assisted-development.mdx | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 develop-docs/engineering-practices/ai-assisted-development.mdx diff --git a/develop-docs/engineering-practices/ai-assisted-development.mdx b/develop-docs/engineering-practices/ai-assisted-development.mdx new file mode 100644 index 0000000000000..80c6353904b8a --- /dev/null +++ b/develop-docs/engineering-practices/ai-assisted-development.mdx @@ -0,0 +1,148 @@ +--- +title: AI-Assisted Development +description: Best practices for using AI coding assistants at Sentry. +sidebar_order: 25 +--- + +This guide covers techniques for getting the most out of AI coding assistants like [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://docs.cursor.com/), and similar tools. + +## The Basics + +AI assistants have broad knowledge but no inherent context about your codebase. They're good at pattern-matching, but they need direction and review. There is a skill to using them. + +**What they're good at:** Boilerplate code, refactoring, finding patterns across files, explaining unfamiliar code, writing tests, catching common bugs, and tedious multi-file changes. + +**What they struggle with:** Novel architecture decisions, understanding implicit business logic, knowing when _not_ to change something, and anything requiring context they can't see. + +Luckily for us, software engineering is full of largely mechanical boilerplate changes that can make great use of agents. That said, **always fully review agent changes before merging**. Pay special attention to tests, where agents tend to write assertions that pass rather than assertions that are correct. + +## Start With a Plan + +The most effective workflow is to have the AI create a plan before writing any code. Describe the task with any constraints, let the AI explore the codebase and propose an approach, then iterate on the plan until it meets your criteria. Once the plan is solid, have the AI implement it. + +Most AI coding tools have a native "plan mode" or "agent mode" that enforces this workflow. Use it! + +**Example workflow:** + +``` +I need to add a new API endpoint POST /api/projects/{id}/archive +that archives a project and all its associated data. This should follow +standard API route conventions and have appropriate testing. Follow the +POST /api/projects/{id}/blah endpoint as an example. Archiving a project +could have many downstream side effects and bugs, can you please also +analyze any potential risks that could happen in other parts of our product +from using this feature. +``` + +After reviewing the proposed plan: + +``` +The plan looks good, but we also need to revoke API keys +when archiving. Update the plan. +``` + +The goal is to allow the agent to work independently for as long as possible without needing your input. + +## Context Files + +Most AI tools support project-level context files that provide instructions and codebase knowledge: + +| Tool | Context File | Docs | +| -------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| Claude Code | `CLAUDE.md` | [docs](https://docs.anthropic.com/en/docs/claude-code/memory) | +| Cursor | `.cursorrules` | [docs](https://docs.cursor.com/context/rules-for-ai) | +| GitHub Copilot | `.github/copilot-instructions.md` | [docs](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) | + +These files can specify coding conventions, architecture decisions, and project-specific guidance. Root-level files are always included, while files in subdirectories are loaded when the AI accesses that directory. Keep them concise and relevant to their scope. + +These files have already been added to our main repos but are by no means complete, please contribute to them! + +## Extending AI Tools + +There are two main ways to extend AI coding tools. **Skills** are prompt templates that teach the AI how to perform specific tasks like following commit conventions. They run inside the AI's context. **MCP (Model Context Protocol)** connects the AI to external services and data sources, providing tools the AI can call. + +### Sentry Skills + +[Sentry Skills](https://github.com/getsentry/skills) are available for Claude Code users: + +| Skill | Description | +| ------------------------ | -------------------------------------------------------- | +| `/commit` | Create commits following Sentry conventions | +| `/create-pr` | Create pull requests with proper formatting | +| `/code-review` | Review code against Sentry practices | +| `/find-bugs` | Find bugs and security vulnerabilities in branch changes | +| `/iterate-pr` | Iterate on a PR until CI passes | +| `/claude-settings-audit` | Generate recommended Claude Code settings for a repo | +| `/brand-guidelines` | Write copy following Sentry brand guidelines | +| `/doc-coauthoring` | Structured workflow for co-authoring docs and specs | + +Install with: + +```bash +claude plugin marketplace add getsentry/skills +claude plugin install sentry-skills@sentry-skills +``` + +See the [Claude Code skills documentation](https://docs.anthropic.com/en/docs/claude-code/skills) for more on how skills work. + +### MCP Tools + +[Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI tools to external systems (think USB-C for AI). While skills teach the AI _how_ to do something, MCP gives it _access_ to things it otherwise couldn't reach: databases, APIs, external services, and the ability to take actions like creating tickets or sending messages. + +Why MCP instead of raw APIs? MCP provides a standardized interface the AI already understands, so there's no need to explain authentication, endpoints, or response formats. The AI just has tools available and knows how to use them. + +For example, with the Sentry MCP server configured, you can ask your AI assistant to "find the most common errors in the billing service this week" and it will query Sentry directly. + +MCP works across tools that support it, including Claude Code and Cursor. See the [MCP documentation](https://modelcontextprotocol.io/docs) for setup and available servers. + +### Subagents + +Subagents are child agents spawned to handle specific tasks in parallel. They each run in their own context window and return a summary to the parent agent. General-purpose and Plan agents inherit the full parent conversation context, while Explore agents start fresh with no prior context (useful for independent search tasks). + +This isolation keeps your main conversation focused. A subagent can read thousands of lines of code, but only returns a concise summary, so your parent context stays clean. Use subagents when searching multiple code paths in parallel, running independent operations simultaneously, or doing large refactors across many files. + +See the [Claude Code subagents documentation](https://code.claude.com/docs/en/sub-agents) for details. + +## Working in Parallel + +The goal is to run multiple AI sessions simultaneously with minimal interruption. A few techniques help achieve this. + +### Git Worktrees + +[Git worktrees](https://git-scm.com/docs/git-worktree) let you check out multiple branches in separate directories, each with its own Claude session. While one agent refactors authentication, another can build an unrelated feature without conflicts or context pollution. + +```bash +git worktree add ../myrepo-feature-x feature-x +cd ../myrepo-feature-x +claude +``` + +Keep worktrees isolated: one branch per worktree, never develop directly in main. For short tasks (under 10 minutes), the setup overhead may not be worth it. + +### Pre-approve Permissions + +Every permission prompt interrupts your flow. Configure allowed tools and commands in your project's settings to let agents work autonomously. In Claude Code, use `/allowed-tools` to see current permissions and `claude config set` to add new ones. + +### Multi-repo Tasks + +When a task spans multiple repositories, use `/add-dir` in Claude Code to add additional directories to the session context. The agent can then read and edit files across repos. + +### Managing Context + +Long sessions accumulate irrelevant context that can degrade performance. Use `/clear` between unrelated tasks to reset the context window. Use `/compact` to summarize and condense the current conversation. Give sessions descriptive names so you can `/resume` them later. + +### Todo Lists + +For complex multi-step tasks, ask the agent to maintain a todo list. This helps it track progress, and you can review the list to course-correct before it goes too far in the wrong direction. Many agents will do this automatically in certain situations but sometimes it can't hurt to ask! + +### Refinement Passes + +Agents, like humans, often need multiple passes to polish code. After the initial implementation, use skills like `/code-simplifier` to clean up verbose or overly defensive patterns. Think of it as a code review step before your actual code review to catch the obvious issues before opening a PR. + +### Let the Agent Fetch Context + +Instead of copying and pasting error messages, give the agent a PR or issue URL and let it fetch the details itself. It can read build failures, status check logs, and PR comments directly using the `gh` CLI. This saves you time and ensures the agent sees the full context. + +### Enable Notifications + +When running multiple sessions, enable terminal notifications so you know when an agent is waiting for input. This lets you context-switch to other work while agents run, without constantly checking back. From 9714126f9fb069c87a2186a65491eb682afe9ca4 Mon Sep 17 00:00:00 2001 From: Trevor Elkins Date: Mon, 2 Feb 2026 10:59:00 -0500 Subject: [PATCH 2/7] Update with Claude team tips --- .../ai-assisted-development.mdx | 54 ++++++++++++++++--- 1 file changed, 48 insertions(+), 6 deletions(-) diff --git a/develop-docs/engineering-practices/ai-assisted-development.mdx b/develop-docs/engineering-practices/ai-assisted-development.mdx index 80c6353904b8a..517f51f74cdac 100644 --- a/develop-docs/engineering-practices/ai-assisted-development.mdx +++ b/develop-docs/engineering-practices/ai-assisted-development.mdx @@ -4,7 +4,7 @@ description: Best practices for using AI coding assistants at Sentry. sidebar_order: 25 --- -This guide covers techniques for getting the most out of AI coding assistants like [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://docs.cursor.com/), and similar tools. +This guide covers techniques for getting the most out of AI coding assistants like [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://docs.cursor.com/), and similar tools. Some of these tips are from [Boris Cherny](https://x.com/bcherny) and the Claude Code team. ## The Basics @@ -18,9 +18,11 @@ Luckily for us, software engineering is full of largely mechanical boilerplate c ## Start With a Plan -The most effective workflow is to have the AI create a plan before writing any code. Describe the task with any constraints, let the AI explore the codebase and propose an approach, then iterate on the plan until it meets your criteria. Once the plan is solid, have the AI implement it. +The most effective workflow is to have the AI create a plan before writing any code. Describe the task with any constraints, let the AI explore the codebase and propose an approach, then iterate on the plan until it meets your criteria. Once the plan is solid, the AI can often one-shot the implementation. -Most AI coding tools have a native "plan mode" or "agent mode" that enforces this workflow. Use it! +Most AI coding tools have a native "plan mode" or "agent mode" that enforces this workflow. Use it! For extra rigor, have one Claude write the plan, then spin up a second Claude to review it as a staff engineer. + +The moment something goes sideways during implementation, switch back to plan mode and re-plan. Don't keep pushing. You can also explicitly tell Claude to enter plan mode for verification steps, not just for the initial build. **Example workflow:** @@ -55,6 +57,8 @@ Most AI tools support project-level context files that provide instructions and These files can specify coding conventions, architecture decisions, and project-specific guidance. Root-level files are always included, while files in subdirectories are loaded when the AI accesses that directory. Keep them concise and relevant to their scope. +Invest in your context file. After every correction, end with: "Update your CLAUDE.md so you don't make that mistake again." Claude is good at writing rules for itself. Ruthlessly edit your CLAUDE.md over time and keep iterating until the mistake rate measurably drops. Some engineers maintain a notes directory for every task or project, updated after every PR, and point CLAUDE.md at it. + These files have already been added to our main repos but are by no means complete, please contribute to them! ## Extending AI Tools @@ -83,7 +87,7 @@ claude plugin marketplace add getsentry/skills claude plugin install sentry-skills@sentry-skills ``` -See the [Claude Code skills documentation](https://docs.anthropic.com/en/docs/claude-code/skills) for more on how skills work. +If you do something more than once a day, turn it into a skill or command. Create your own skills and commit them to git so you can reuse them across projects. See the [Claude Code skills documentation](https://docs.anthropic.com/en/docs/claude-code/skills) for more on how skills work. ### MCP Tools @@ -101,6 +105,8 @@ Subagents are child agents spawned to handle specific tasks in parallel. They ea This isolation keeps your main conversation focused. A subagent can read thousands of lines of code, but only returns a concise summary, so your parent context stays clean. Use subagents when searching multiple code paths in parallel, running independent operations simultaneously, or doing large refactors across many files. +Append "use subagents" to any request where you want Claude to throw more compute at the problem. You can also route permission requests to Opus 4.5 via a [hook](https://code.claude.com/docs/en/hooks#permissionrequest) to scan for attacks and auto-approve the safe ones. + See the [Claude Code subagents documentation](https://code.claude.com/docs/en/sub-agents) for details. ## Working in Parallel @@ -109,7 +115,7 @@ The goal is to run multiple AI sessions simultaneously with minimal interruption ### Git Worktrees -[Git worktrees](https://git-scm.com/docs/git-worktree) let you check out multiple branches in separate directories, each with its own Claude session. While one agent refactors authentication, another can build an unrelated feature without conflicts or context pollution. +[Git worktrees](https://git-scm.com/docs/git-worktree) let you check out multiple branches in separate directories, each with its own Claude session. Spinning up 3-5 worktrees at once, each running its own Claude session in parallel, is one of the biggest productivity unlocks. While one agent refactors authentication, another can build an unrelated feature without conflicts or context pollution. ```bash git worktree add ../myrepo-feature-x feature-x @@ -117,7 +123,9 @@ cd ../myrepo-feature-x claude ``` -Keep worktrees isolated: one branch per worktree, never develop directly in main. For short tasks (under 10 minutes), the setup overhead may not be worth it. +Name your worktrees and set up shell aliases (`za`, `zb`, `zc`) so you can hop between them in one keystroke. Some people keep a dedicated "analysis" worktree that's only for reading logs and running queries. + +Keep worktrees isolated: one branch per worktree, never develop directly in main. For short tasks, the setup overhead may not be worth it. See [Run parallel Claude Code sessions with git worktrees](https://code.claude.com/docs/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) for more. ### Pre-approve Permissions @@ -146,3 +154,37 @@ Instead of copying and pasting error messages, give the agent a PR or issue URL ### Enable Notifications When running multiple sessions, enable terminal notifications so you know when an agent is waiting for input. This lets you context-switch to other work while agents run, without constantly checking back. + +### Terminal Setup + +[Ghostty](https://ghostty.org/) is a popular choice for its synchronized rendering, 24-bit color, and proper unicode support. Use `/statusline` to customize your status bar to always show context usage and current git branch. Color-code and name your terminal tabs, one tab per task or worktree. Some people use tmux for this. + +Use voice dictation. You speak 3x faster than you type, and your prompts get way more detailed as a result (hit fn twice on macOS). See the [terminal configuration docs](https://code.claude.com/docs/en/terminal-config) for more tips. + +## Bug Fixing + +Claude fixes most bugs by itself with minimal guidance. Enable the Slack MCP, paste a Slack bug thread into Claude, and just say "fix." + +Or just say "Go fix the failing CI tests." Don't micromanage how. Point Claude at docker logs to troubleshoot distributed systems. + +## Prompting Techniques + +Challenge Claude. Say "Grill me on these changes and don't make a PR until I pass your test." Make Claude be your reviewer. Or say "Prove to me this works" and have Claude diff behavior between main and your feature branch. + +After a mediocre fix, say: "Knowing everything you know now, scrap this and implement the elegant solution." + +Write detailed specs and reduce ambiguity before handing work off. The more specific you are, the better the output. + +## Data & Analytics + +Ask Claude Code to use the `bq` CLI to pull and analyze metrics on the fly. You can create a BigQuery skill and check it into the codebase so everyone on the team can run analytics queries directly in Claude Code. + +This works for any database that has a CLI, MCP, or API. + +## Learning with Claude + +Enable the "Explanatory" or "Learning" output style in `/config` to have Claude explain the _why_ behind its changes. + +Have Claude generate a visual HTML presentation explaining unfamiliar code. Ask Claude to draw ASCII diagrams of new protocols and codebases to help you understand them. + +You can even build a spaced-repetition learning skill: you explain your understanding, Claude asks follow-ups to fill gaps, and stores the result. From 47642281afb4151fd6fbb2ef9893f11c73476a71 Mon Sep 17 00:00:00 2001 From: Trevor Elkins Date: Thu, 12 Feb 2026 18:08:06 -0500 Subject: [PATCH 3/7] update --- .../ai-assisted-development.mdx | 109 ++++++++++++++++-- 1 file changed, 100 insertions(+), 9 deletions(-) diff --git a/develop-docs/engineering-practices/ai-assisted-development.mdx b/develop-docs/engineering-practices/ai-assisted-development.mdx index 517f51f74cdac..4804ff746876f 100644 --- a/develop-docs/engineering-practices/ai-assisted-development.mdx +++ b/develop-docs/engineering-practices/ai-assisted-development.mdx @@ -65,6 +65,14 @@ These files have already been added to our main repos but are by no means comple There are two main ways to extend AI coding tools. **Skills** are prompt templates that teach the AI how to perform specific tasks like following commit conventions. They run inside the AI's context. **MCP (Model Context Protocol)** connects the AI to external services and data sources, providing tools the AI can call. +### Plugins + +Plugins are the primary way to install extensions in Claude Code. A plugin can bundle LSPs (available for every major language), MCPs, skills, agents, and custom hooks into a single installable package. + +Install plugins from the official Anthropic plugin marketplace, or create a private marketplace for your company. Check the `settings.json` into your codebase to auto-add marketplaces for your team so everyone gets the same tooling. + +Run `/plugin` to browse and install plugins. See the [plugin documentation](https://code.claude.com/docs/en/discover-plugins) for more. + ### Sentry Skills [Sentry Skills](https://github.com/getsentry/skills) are available for Claude Code users: @@ -109,6 +117,35 @@ Append "use subagents" to any request where you want Claude to throw more comput See the [Claude Code subagents documentation](https://code.claude.com/docs/en/sub-agents) for details. +### Custom Agents + +Custom agents let you define specialized personas with their own tools, permissions, and models. Drop `.md` files in `.claude/agents/` to create them. Each agent can have a custom name, color, tool set, pre-allowed and pre-disallowed tools, permission mode, and model. + +You can also set a default agent for your main conversation using the `"agent"` field in `settings.json` or the `--agent` CLI flag. This is useful for teams that want a consistent base configuration. + +Run `/agents` to get started, or see the [custom agents documentation](https://code.claude.com/docs/en/sub-agents). + +## Recommended Tools + +Connect your AI assistant to the services your team already uses. These are the MCP servers and CLIs we've found most useful at Sentry. + +| Tool | What it gives you | Setup | +| ---- | ----------------- | ----- | +| [Sentry MCP](https://docs.sentry.io/product/sentry-mcp/) | Query errors, search issues, analyze traces, and get root cause analysis directly from your editor. | `claude mcp add sentry -- npx @sentry/mcp` | +| [Linear MCP](https://github.com/jerhadf/linear-mcp-server) | Create, search, and update Linear issues without leaving your session. Great for turning bug findings into tickets on the spot. | See repo README | +| [Notion MCP](https://github.com/makenotion/notion-mcp-server) | Search and read Notion pages. Useful for pulling in specs, RFCs, and team docs as context. | See repo README | +| [Slack MCP](https://github.com/nicholasgriffintn/slack-mcp-server) | Read Slack threads and channels. Paste a bug report thread and say "fix." | See repo README | + +### CLIs + +AI assistants can use any CLI tool you have installed. A few that work especially well: + +- **`gcloud`** — Fetch logs, query BigQuery, and inspect GCP resources. Point Claude at `gcloud logging read` output to troubleshoot production issues. +- **`gh`** — Read PRs, issues, CI logs, and review comments from GitHub. +- **`bq`** — Run BigQuery queries for ad-hoc analytics (see [Data & Analytics](#data--analytics)). + +If there's a service your team uses daily and it has a CLI or MCP server, connect it. The fewer context switches between your editor and browser, the better. + ## Working in Parallel The goal is to run multiple AI sessions simultaneously with minimal interruption. A few techniques help achieve this. @@ -129,7 +166,26 @@ Keep worktrees isolated: one branch per worktree, never develop directly in main ### Pre-approve Permissions -Every permission prompt interrupts your flow. Configure allowed tools and commands in your project's settings to let agents work autonomously. In Claude Code, use `/allowed-tools` to see current permissions and `claude config set` to add new ones. +Every permission prompt interrupts your flow. Run `/permissions` in Claude Code to manage your allow and block lists. Check these into your team's `settings.json` so everyone benefits. + +Claude Code supports full wildcard syntax for permissions. For example, `Bash(bun run *)` pre-approves all `bun run` commands, and `Edit(/docs/**)` allows edits to any file under `/docs/`. See the [permissions documentation](https://code.claude.com/docs/en/permissions) for details. + +### Sandboxing + +Enable Claude Code's [open source sandbox runtime](https://github.com/anthropic-experimental/sandbox-runtime) to improve safety while reducing permission prompts. Sandboxing runs on your machine and supports both file and network isolation. + +Run `/sandbox` to enable it. See the [sandboxing documentation](https://code.claude.com/docs/en/sandboxing) for details. + +### Hooks + +Hooks let you deterministically hook into Claude's lifecycle. Use them to: + +- Automatically route permission requests to Slack or Opus for approval +- Nudge Claude to keep going when it reaches the end of a turn (you can use a prompt or kick off an agent to decide whether Claude should continue) +- Pre-process or post-process tool calls, for example to add your own logging +- Enable terminal notifications when an agent is waiting for input + +Ask Claude to add a hook to get started, or see the [hooks documentation](https://code.claude.com/docs/en/hooks). ### Multi-repo Tasks @@ -153,13 +209,7 @@ Instead of copying and pasting error messages, give the agent a PR or issue URL ### Enable Notifications -When running multiple sessions, enable terminal notifications so you know when an agent is waiting for input. This lets you context-switch to other work while agents run, without constantly checking back. - -### Terminal Setup - -[Ghostty](https://ghostty.org/) is a popular choice for its synchronized rendering, 24-bit color, and proper unicode support. Use `/statusline` to customize your status bar to always show context usage and current git branch. Color-code and name your terminal tabs, one tab per task or worktree. Some people use tmux for this. - -Use voice dictation. You speak 3x faster than you type, and your prompts get way more detailed as a result (hit fn twice on macOS). See the [terminal configuration docs](https://code.claude.com/docs/en/terminal-config) for more tips. +When running multiple sessions, enable terminal notifications so you know when an agent is waiting for input. iTerm2 has built-in notification support, or you can use a custom notifications hook. This lets you context-switch to other work while agents run, without constantly checking back. ## Bug Fixing @@ -183,8 +233,49 @@ This works for any database that has a CLI, MCP, or API. ## Learning with Claude -Enable the "Explanatory" or "Learning" output style in `/config` to have Claude explain the _why_ behind its changes. +Run `/config` and set an output style to adjust Claude's tone and format. The **"Explanatory"** style is great when getting familiar with a new codebase, as Claude explains frameworks and code patterns as it works. The **"Learning"** style coaches you through making code changes yourself instead of writing the code for you. You can also create custom output styles to adjust Claude's voice however you like. See the [output styles documentation](https://code.claude.com/docs/en/output-styles) for details. Have Claude generate a visual HTML presentation explaining unfamiliar code. Ask Claude to draw ASCII diagrams of new protocols and codebases to help you understand them. You can even build a spaced-repetition learning skill: you explain your understanding, Claude asks follow-ups to fill gaps, and stores the result. + +## Personalizing Claude Code + +Claude Code is built to work well out of the box, but almost everything is customizable. + +### Terminal Setup + +[Ghostty](https://ghostty.org/) is a popular choice for its synchronized rendering, 24-bit color, and proper unicode support. Color-code and name your terminal tabs, one tab per task or worktree. Some people use tmux for this. + +- **Theme:** Run `/config` to set light or dark mode. +- **Newlines:** If you use Claude Code in an IDE terminal, Apple Terminal, Warp, or Alacritty, run `/terminal-setup` to enable shift+enter for newlines (so you don't need to type `\`). +- **Vim mode:** Run `/vim` to enable vim keybindings. +- **Voice dictation:** You speak 3x faster than you type, and your prompts get way more detailed as a result (hit fn twice on macOS). + +See the [terminal configuration docs](https://code.claude.com/docs/en/terminal-config) for more. + +### Effort Level + +Run `/model` to pick your preferred effort level: + +- **Low:** Fewer tokens, faster responses. +- **Medium:** Balanced behavior. +- **High:** More tokens, more intelligence. + +Use High for complex tasks requiring deep reasoning, and Low or Medium for quick edits and straightforward questions. + +### Status Line + +Custom status lines appear below the composer and can show model, directory, remaining context, cost, and more. Run `/statusline` to configure yours, or have Claude generate one based on your shell config. See the [status line documentation](https://code.claude.com/docs/en/statusline). + +### Keybindings + +Every keybinding in Claude Code is customizable. Run `/keybindings` to remap any key. Settings live-reload so you can see how changes feel immediately. + +### Spinner Verbs + +You can customize the spinner verbs that display while Claude is working. Ask Claude to customize your spinner verbs to replace the defaults with your own. Check the `settings.json` into source control to share them with your team. + +### Sharing Settings + +Check your `settings.json` into git so your team benefits from your configuration. Claude Code supports configuring settings at the codebase level, for a sub-folder, for just yourself, or via enterprise-wide policies. You can also use the `"env"` field in `settings.json` to set environment variables without wrapper scripts. Claude Code supports 37 settings and 84 environment variables. See the [settings documentation](https://code.claude.com/docs/en/settings) for the full reference. From fd10891bbfeac2ed3cd0b72c51de603d33657b53 Mon Sep 17 00:00:00 2001 From: Trevor Elkins Date: Thu, 12 Feb 2026 18:41:21 -0500 Subject: [PATCH 4/7] docs(develop): update AI-assisted development guide with Claude Code customization tips Add plugins, custom agents, sandboxing, hooks, permissions wildcards, recommended tools, spec-based development, and terminal setup tips based on latest Claude Code team insights. Co-Authored-By: Claude --- .../ai-assisted-development.mdx | 75 ++++++------------- 1 file changed, 24 insertions(+), 51 deletions(-) diff --git a/develop-docs/engineering-practices/ai-assisted-development.mdx b/develop-docs/engineering-practices/ai-assisted-development.mdx index 2f9dce9ddc0a2..b08bed13da2a0 100644 --- a/develop-docs/engineering-practices/ai-assisted-development.mdx +++ b/develop-docs/engineering-practices/ai-assisted-development.mdx @@ -45,6 +45,8 @@ when archiving. Update the plan. The goal is to allow the agent to work independently for as long as possible without needing your input. +An alternative to explicit plan mode is **spec-based development**: start with a minimal spec or prompt and ask Claude to interview you (using skills like [brainstorming](https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md) that leverage `AskUserQuestion` to refine requirements interactively). Once the spec is solid, start a new session to execute it. This separates the thinking from the doing and keeps the implementation context clean. + ## Context Files Most AI tools support project-level context files that provide instructions and codebase knowledge: @@ -107,16 +109,6 @@ For example, with the Sentry MCP server configured, you can ask your AI assistan MCP works across tools that support it, including Claude Code and Cursor. See the [MCP documentation](https://modelcontextprotocol.io/docs) for setup and available servers. -### Subagents - -Subagents are child agents spawned to handle specific tasks in parallel. They each run in their own context window and return a summary to the parent agent. General-purpose and Plan agents inherit the full parent conversation context, while Explore agents start fresh with no prior context (useful for independent search tasks). - -This isolation keeps your main conversation focused. A subagent can read thousands of lines of code, but only returns a concise summary, so your parent context stays clean. Use subagents when searching multiple code paths in parallel, running independent operations simultaneously, or doing large refactors across many files. - -Append "use subagents" to any request where you want Claude to throw more compute at the problem. You can also route permission requests to Opus 4.5 via a [hook](https://code.claude.com/docs/en/hooks#permissionrequest) to scan for attacks and auto-approve the safe ones. - -See the [Claude Code subagents documentation](https://code.claude.com/docs/en/sub-agents) for details. - ### Custom Agents Custom agents let you define specialized personas with their own tools, permissions, and models. Drop `.md` files in `.claude/agents/` to create them. Each agent can have a custom name, color, tool set, pre-allowed and pre-disallowed tools, permission mode, and model. @@ -150,6 +142,16 @@ If there's a service your team uses daily and it has a CLI or MCP server, connec The goal is to run multiple AI sessions simultaneously with minimal interruption. A few techniques help achieve this. +### Subagents + +Subagents are child agents spawned to handle specific tasks in parallel. They each run in their own context window and return a summary to the parent agent. General-purpose and Plan agents inherit the full parent conversation context, while Explore agents start fresh with no prior context (useful for independent search tasks). + +This isolation keeps your main conversation focused. A subagent can read thousands of lines of code, but only returns a concise summary, so your parent context stays clean. Use subagents when searching multiple code paths in parallel, running independent operations simultaneously, or doing large refactors across many files. + +Append "use subagents" to any request where you want Claude to throw more compute at the problem. You can also route permission requests to Opus 4.5 via a [hook](https://code.claude.com/docs/en/hooks#permissionrequest) to scan for attacks and auto-approve the safe ones. + +See the [Claude Code subagents documentation](https://code.claude.com/docs/en/sub-agents) for details. + ### Git Worktrees [Git worktrees](https://git-scm.com/docs/git-worktree) let you check out multiple branches in separate directories, each with its own Claude session. Spinning up 3-5 worktrees at once, each running its own Claude session in parallel, is one of the biggest productivity unlocks. While one agent refactors authentication, another can build an unrelated feature without conflicts or context pollution. @@ -211,6 +213,18 @@ Instead of copying and pasting error messages, give the agent a PR or issue URL When running multiple sessions, enable terminal notifications so you know when an agent is waiting for input. iTerm2 has built-in notification support, or you can use a custom notifications hook. This lets you context-switch to other work while agents run, without constantly checking back. +### Terminal Setup + +[Ghostty](https://ghostty.org/) is a popular choice for its synchronized rendering, 24-bit color, and proper unicode support. Color-code and name your terminal tabs, one tab per task or worktree. Some people use tmux for this. + +- **Theme:** Run `/config` to set light or dark mode. +- **Newlines:** If you use Claude Code in an IDE terminal, Apple Terminal, Warp, or Alacritty, run `/terminal-setup` to enable shift+enter for newlines (so you don't need to type `\`). +- **Vim mode:** Run `/vim` to enable vim keybindings. +- **Status line:** Run `/statusline` to show model, directory, remaining context, cost, and more below the composer. See the [status line documentation](https://code.claude.com/docs/en/statusline). +- **Voice dictation:** You speak 3x faster than you type, and your prompts get way more detailed as a result (hit fn twice on macOS). + +See the [terminal configuration docs](https://code.claude.com/docs/en/terminal-config) for more. + ## Bug Fixing Claude fixes most bugs by itself with minimal guidance. Enable the Slack MCP, paste a Slack bug thread into Claude, and just say "fix." @@ -238,44 +252,3 @@ Run `/config` and set an output style to adjust Claude's tone and format. The ** Have Claude generate a visual HTML presentation explaining unfamiliar code. Ask Claude to draw ASCII diagrams of new protocols and codebases to help you understand them. You can even build a spaced-repetition learning skill: you explain your understanding, Claude asks follow-ups to fill gaps, and stores the result. - -## Personalizing Claude Code - -Claude Code is built to work well out of the box, but almost everything is customizable. - -### Terminal Setup - -[Ghostty](https://ghostty.org/) is a popular choice for its synchronized rendering, 24-bit color, and proper unicode support. Color-code and name your terminal tabs, one tab per task or worktree. Some people use tmux for this. - -- **Theme:** Run `/config` to set light or dark mode. -- **Newlines:** If you use Claude Code in an IDE terminal, Apple Terminal, Warp, or Alacritty, run `/terminal-setup` to enable shift+enter for newlines (so you don't need to type `\`). -- **Vim mode:** Run `/vim` to enable vim keybindings. -- **Voice dictation:** You speak 3x faster than you type, and your prompts get way more detailed as a result (hit fn twice on macOS). - -See the [terminal configuration docs](https://code.claude.com/docs/en/terminal-config) for more. - -### Effort Level - -Run `/model` to pick your preferred effort level: - -- **Low:** Fewer tokens, faster responses. -- **Medium:** Balanced behavior. -- **High:** More tokens, more intelligence. - -Use High for complex tasks requiring deep reasoning, and Low or Medium for quick edits and straightforward questions. - -### Status Line - -Custom status lines appear below the composer and can show model, directory, remaining context, cost, and more. Run `/statusline` to configure yours, or have Claude generate one based on your shell config. See the [status line documentation](https://code.claude.com/docs/en/statusline). - -### Keybindings - -Every keybinding in Claude Code is customizable. Run `/keybindings` to remap any key. Settings live-reload so you can see how changes feel immediately. - -### Spinner Verbs - -You can customize the spinner verbs that display while Claude is working. Ask Claude to customize your spinner verbs to replace the defaults with your own. Check the `settings.json` into source control to share them with your team. - -### Sharing Settings - -Check your `settings.json` into git so your team benefits from your configuration. Claude Code supports configuring settings at the codebase level, for a sub-folder, for just yourself, or via enterprise-wide policies. You can also use the `"env"` field in `settings.json` to set environment variables without wrapper scripts. Claude Code supports 37 settings and 84 environment variables. See the [settings documentation](https://code.claude.com/docs/en/settings) for the full reference. From cd2d5eb93aec0fc9bc1e5a021c86b8ac5cf140be Mon Sep 17 00:00:00 2001 From: Trevor Elkins Date: Fri, 13 Feb 2026 14:48:18 -0500 Subject: [PATCH 5/7] fixes --- .../ai-assisted-development.mdx | 104 +++++++++--------- 1 file changed, 54 insertions(+), 50 deletions(-) diff --git a/develop-docs/engineering-practices/ai-assisted-development.mdx b/develop-docs/engineering-practices/ai-assisted-development.mdx index b08bed13da2a0..980b0b88d4206 100644 --- a/develop-docs/engineering-practices/ai-assisted-development.mdx +++ b/develop-docs/engineering-practices/ai-assisted-development.mdx @@ -16,38 +16,7 @@ AI assistants have broad knowledge but no inherent context about your codebase. Luckily for us, software engineering is full of largely mechanical boilerplate changes that can make great use of agents. That said, **always fully review agent changes before merging**. Pay special attention to tests, where agents tend to write assertions that pass rather than assertions that are correct. -## Start With a Plan - -The most effective workflow is to have the AI create a plan before writing any code. Describe the task with any constraints, let the AI explore the codebase and propose an approach, then iterate on the plan until it meets your criteria. Once the plan is solid, the AI can often one-shot the implementation. - -Most AI coding tools have a native "plan mode" or "agent mode" that enforces this workflow. Use it! For extra rigor, have one Claude write the plan, then spin up a second Claude to review it as a staff engineer. - -The moment something goes sideways during implementation, switch back to plan mode and re-plan. Don't keep pushing. You can also explicitly tell Claude to enter plan mode for verification steps, not just for the initial build. - -**Example workflow:** - -``` -I need to add a new API endpoint POST /api/projects/{id}/archive -that archives a project and all its associated data. This should follow -standard API route conventions and have appropriate testing. Follow the -POST /api/projects/{id}/blah endpoint as an example. Archiving a project -could have many downstream side effects and bugs, can you please also -analyze any potential risks that could happen in other parts of our product -from using this feature. -``` - -After reviewing the proposed plan: - -``` -The plan looks good, but we also need to revoke API keys -when archiving. Update the plan. -``` - -The goal is to allow the agent to work independently for as long as possible without needing your input. - -An alternative to explicit plan mode is **spec-based development**: start with a minimal spec or prompt and ask Claude to interview you (using skills like [brainstorming](https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md) that leverage `AskUserQuestion` to refine requirements interactively). Once the spec is solid, start a new session to execute it. This separates the thinking from the doing and keeps the implementation context clean. - -## Context Files +### Context Files Most AI tools support project-level context files that provide instructions and codebase knowledge: @@ -63,11 +32,11 @@ Invest in your context file. After every correction, end with: "Update your CLAU These files have already been added to our main repos but are by no means complete, please contribute to them! -## Extending AI Tools +### Extending AI Tools There are two main ways to extend AI coding tools. **Skills** are prompt templates that teach the AI how to perform specific tasks like following commit conventions. They run inside the AI's context. **MCP (Model Context Protocol)** connects the AI to external services and data sources, providing tools the AI can call. -### Plugins +#### Plugins Plugins are the primary way to install extensions in Claude Code. A plugin can bundle LSPs (available for every major language), MCPs, skills, agents, and custom hooks into a single installable package. @@ -75,7 +44,7 @@ Install plugins from the official Anthropic plugin marketplace, or create a priv Run `/plugin` to browse and install plugins. See the [plugin documentation](https://code.claude.com/docs/en/discover-plugins) for more. -### Sentry Skills +#### Sentry Skills [Sentry Skills](https://github.com/getsentry/skills) are available for Claude Code users: @@ -99,7 +68,7 @@ claude plugin install sentry-skills@sentry-skills If you do something more than once a day, turn it into a skill or command. Create your own skills and commit them to git so you can reuse them across projects. See the [Claude Code skills documentation](https://docs.anthropic.com/en/docs/claude-code/skills) for more on how skills work. -### MCP Tools +#### MCP Tools [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI tools to external systems (think USB-C for AI). While skills teach the AI _how_ to do something, MCP gives it _access_ to things it otherwise couldn't reach: databases, APIs, external services, and the ability to take actions like creating tickets or sending messages. @@ -109,7 +78,7 @@ For example, with the Sentry MCP server configured, you can ask your AI assistan MCP works across tools that support it, including Claude Code and Cursor. See the [MCP documentation](https://modelcontextprotocol.io/docs) for setup and available servers. -### Custom Agents +#### Custom Agents Custom agents let you define specialized personas with their own tools, permissions, and models. Drop `.md` files in `.claude/agents/` to create them. Each agent can have a custom name, color, tool set, pre-allowed and pre-disallowed tools, permission mode, and model. @@ -117,7 +86,7 @@ You can also set a default agent for your main conversation using the `"agent"` Run `/agents` to get started, or see the [custom agents documentation](https://code.claude.com/docs/en/sub-agents). -## Recommended Tools +### Recommended Tools Connect your AI assistant to the services your team already uses. These are the MCP servers and CLIs we've found most useful at Sentry. @@ -128,7 +97,7 @@ Connect your AI assistant to the services your team already uses. These are the | [Notion MCP](https://github.com/makenotion/notion-mcp-server) | Search and read Notion pages. Useful for pulling in specs, RFCs, and team docs as context. | See repo README | | [Slack MCP](https://github.com/nicholasgriffintn/slack-mcp-server) | Read Slack threads and channels. Paste a bug report thread and say "fix." | See repo README | -### CLIs +#### CLIs AI assistants can use any CLI tool you have installed. A few that work especially well: @@ -138,6 +107,47 @@ AI assistants can use any CLI tool you have installed. A few that work especiall If there's a service your team uses daily and it has a CLI or MCP server, connect it. The fewer context switches between your editor and browser, the better. +## Prompting + +### Start With a Plan + +The most effective workflow is to have the AI create a plan before writing any code. Describe the task with any constraints, let the AI explore the codebase and propose an approach, then iterate on the plan until it meets your criteria. Once the plan is solid, the AI can often one-shot the implementation. + +Most AI coding tools have a native "plan mode" or "agent mode" that enforces this workflow. Use it! For extra rigor, have one Claude write the plan, then spin up a second Claude to review it as a staff engineer. + +The moment something goes sideways during implementation, switch back to plan mode and re-plan. Don't keep pushing. You can also explicitly tell Claude to enter plan mode for verification steps, not just for the initial build. + +**Example workflow:** + +``` +I need to add a new API endpoint POST /api/projects/{id}/archive +that archives a project and all its associated data. This should follow +standard API route conventions and have appropriate testing. Follow the +POST /api/projects/{id}/blah endpoint as an example. Archiving a project +could have many downstream side effects and bugs, can you please also +analyze any potential risks that could happen in other parts of our product +from using this feature. +``` + +After reviewing the proposed plan: + +``` +The plan looks good, but we also need to revoke API keys +when archiving. Update the plan. +``` + +The goal is to allow the agent to work independently for as long as possible without needing your input. + +An alternative to explicit plan mode is **spec-based development**: start with a minimal spec or prompt and ask Claude to interview you (using skills like [brainstorming](https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md) that leverage `AskUserQuestion` to refine requirements interactively). Once the spec is solid, start a new session to execute it. This separates the thinking from the doing and keeps the implementation context clean. + +### Techniques + +Challenge Claude. Say "Grill me on these changes and don't make a PR until I pass your test." Make Claude be your reviewer. Or say "Prove to me this works" and have Claude diff behavior between main and your feature branch. + +After a mediocre fix, say: "Knowing everything you know now, scrap this and implement the elegant solution." + +Write detailed specs and reduce ambiguity before handing work off. The more specific you are, the better the output. + ## Working in Parallel The goal is to run multiple AI sessions simultaneously with minimal interruption. A few techniques help achieve this. @@ -225,27 +235,21 @@ When running multiple sessions, enable terminal notifications so you know when a See the [terminal configuration docs](https://code.claude.com/docs/en/terminal-config) for more. -## Bug Fixing +## Workflows + +### Bug Fixing Claude fixes most bugs by itself with minimal guidance. Enable the Slack MCP, paste a Slack bug thread into Claude, and just say "fix." Or just say "Go fix the failing CI tests." Don't micromanage how. Point Claude at docker logs to troubleshoot distributed systems. -## Prompting Techniques - -Challenge Claude. Say "Grill me on these changes and don't make a PR until I pass your test." Make Claude be your reviewer. Or say "Prove to me this works" and have Claude diff behavior between main and your feature branch. - -After a mediocre fix, say: "Knowing everything you know now, scrap this and implement the elegant solution." - -Write detailed specs and reduce ambiguity before handing work off. The more specific you are, the better the output. - -## Data & Analytics +### Data & Analytics Ask Claude Code to use the `bq` CLI to pull and analyze metrics on the fly. You can create a BigQuery skill and check it into the codebase so everyone on the team can run analytics queries directly in Claude Code. This works for any database that has a CLI, MCP, or API. -## Learning with Claude +### Learning with Claude Run `/config` and set an output style to adjust Claude's tone and format. The **"Explanatory"** style is great when getting familiar with a new codebase, as Claude explains frameworks and code patterns as it works. The **"Learning"** style coaches you through making code changes yourself instead of writing the code for you. You can also create custom output styles to adjust Claude's voice however you like. See the [output styles documentation](https://code.claude.com/docs/en/output-styles) for details. From 5ee0f39795e74871b37927e254bb9f9eae909197 Mon Sep 17 00:00:00 2001 From: Trevor Elkins Date: Fri, 13 Feb 2026 15:01:51 -0500 Subject: [PATCH 6/7] rearrange --- .../ai-assisted-development.mdx | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/develop-docs/engineering-practices/ai-assisted-development.mdx b/develop-docs/engineering-practices/ai-assisted-development.mdx index 980b0b88d4206..c0b1975b3437d 100644 --- a/develop-docs/engineering-practices/ai-assisted-development.mdx +++ b/develop-docs/engineering-practices/ai-assisted-development.mdx @@ -152,15 +152,15 @@ Write detailed specs and reduce ambiguity before handing work off. The more spec The goal is to run multiple AI sessions simultaneously with minimal interruption. A few techniques help achieve this. -### Subagents +### Pre-approve Permissions -Subagents are child agents spawned to handle specific tasks in parallel. They each run in their own context window and return a summary to the parent agent. General-purpose and Plan agents inherit the full parent conversation context, while Explore agents start fresh with no prior context (useful for independent search tasks). +Every permission prompt interrupts your flow. Run `/permissions` in Claude Code to manage your allow and block lists. Check these into your team's `settings.json` so everyone benefits. -This isolation keeps your main conversation focused. A subagent can read thousands of lines of code, but only returns a concise summary, so your parent context stays clean. Use subagents when searching multiple code paths in parallel, running independent operations simultaneously, or doing large refactors across many files. +Claude Code supports full wildcard syntax for permissions. For example, `Bash(bun run *)` pre-approves all `bun run` commands, and `Edit(/docs/**)` allows edits to any file under `/docs/`. See the [permissions documentation](https://code.claude.com/docs/en/permissions) for details. -Append "use subagents" to any request where you want Claude to throw more compute at the problem. You can also route permission requests to Opus 4.5 via a [hook](https://code.claude.com/docs/en/hooks#permissionrequest) to scan for attacks and auto-approve the safe ones. +### Multi-repo Tasks -See the [Claude Code subagents documentation](https://code.claude.com/docs/en/sub-agents) for details. +When a task spans multiple repositories, use `/add-dir` in Claude Code to add additional directories to the session context. The agent can then read and edit files across repos. ### Git Worktrees @@ -176,11 +176,15 @@ Name your worktrees and set up shell aliases (`za`, `zb`, `zc`) so you can hop b Keep worktrees isolated: one branch per worktree, never develop directly in main. For short tasks, the setup overhead may not be worth it. See [Run parallel Claude Code sessions with git worktrees](https://code.claude.com/docs/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) for more. -### Pre-approve Permissions +### Subagents -Every permission prompt interrupts your flow. Run `/permissions` in Claude Code to manage your allow and block lists. Check these into your team's `settings.json` so everyone benefits. +Subagents are child agents spawned to handle specific tasks in parallel. They each run in their own context window and return a summary to the parent agent. General-purpose and Plan agents inherit the full parent conversation context, while Explore agents start fresh with no prior context (useful for independent search tasks). -Claude Code supports full wildcard syntax for permissions. For example, `Bash(bun run *)` pre-approves all `bun run` commands, and `Edit(/docs/**)` allows edits to any file under `/docs/`. See the [permissions documentation](https://code.claude.com/docs/en/permissions) for details. +This isolation keeps your main conversation focused. A subagent can read thousands of lines of code, but only returns a concise summary, so your parent context stays clean. Use subagents when searching multiple code paths in parallel, running independent operations simultaneously, or doing large refactors across many files. + +Append "use subagents" to any request where you want Claude to throw more compute at the problem. You can also route permission requests to Opus 4.5 via a [hook](https://code.claude.com/docs/en/hooks#permissionrequest) to scan for attacks and auto-approve the safe ones. + +See the [Claude Code subagents documentation](https://code.claude.com/docs/en/sub-agents) for details. ### Sandboxing @@ -199,10 +203,6 @@ Hooks let you deterministically hook into Claude's lifecycle. Use them to: Ask Claude to add a hook to get started, or see the [hooks documentation](https://code.claude.com/docs/en/hooks). -### Multi-repo Tasks - -When a task spans multiple repositories, use `/add-dir` in Claude Code to add additional directories to the session context. The agent can then read and edit files across repos. - ### Managing Context Long sessions accumulate irrelevant context that can degrade performance. Use `/clear` between unrelated tasks to reset the context window. Use `/compact` to condense the conversation, or `/compact [instructions]` to preserve specific information like core definitions or debugging notes. Give sessions descriptive names so you can `/resume` them later. From ea8dfadddb66965417c1297749dd226d6b0ae3f4 Mon Sep 17 00:00:00 2001 From: Trevor Elkins Date: Fri, 13 Feb 2026 15:14:43 -0500 Subject: [PATCH 7/7] moar --- .../ai-assisted-development.mdx | 36 +++++++------------ 1 file changed, 12 insertions(+), 24 deletions(-) diff --git a/develop-docs/engineering-practices/ai-assisted-development.mdx b/develop-docs/engineering-practices/ai-assisted-development.mdx index c0b1975b3437d..c619f9b65a3ca 100644 --- a/develop-docs/engineering-practices/ai-assisted-development.mdx +++ b/develop-docs/engineering-practices/ai-assisted-development.mdx @@ -148,6 +148,18 @@ After a mediocre fix, say: "Knowing everything you know now, scrap this and impl Write detailed specs and reduce ambiguity before handing work off. The more specific you are, the better the output. +### Managing Context + +Long sessions accumulate irrelevant context that can degrade performance. Use `/clear` between unrelated tasks to reset the context window. Use `/compact` to condense the conversation, or `/compact [instructions]` to preserve specific information like core definitions or debugging notes. Give sessions descriptive names so you can `/resume` them later. Run `/statusline` to keep track of remaining context at a glance. + +### Todo Lists + +For complex multi-step tasks, ask the agent to maintain a todo list. This helps it track progress, and you can review the list to course-correct before it goes too far in the wrong direction. Many agents will do this automatically in certain situations but sometimes it can't hurt to ask! + +### Refinement Passes + +Agents, like humans, often need multiple passes to polish code. After the initial implementation, use skills like `/code-simplifier` to clean up verbose or overly defensive patterns. Think of it as a code review step before your actual code review to catch the obvious issues before opening a PR. + ## Working in Parallel The goal is to run multiple AI sessions simultaneously with minimal interruption. A few techniques help achieve this. @@ -203,18 +215,6 @@ Hooks let you deterministically hook into Claude's lifecycle. Use them to: Ask Claude to add a hook to get started, or see the [hooks documentation](https://code.claude.com/docs/en/hooks). -### Managing Context - -Long sessions accumulate irrelevant context that can degrade performance. Use `/clear` between unrelated tasks to reset the context window. Use `/compact` to condense the conversation, or `/compact [instructions]` to preserve specific information like core definitions or debugging notes. Give sessions descriptive names so you can `/resume` them later. - -### Todo Lists - -For complex multi-step tasks, ask the agent to maintain a todo list. This helps it track progress, and you can review the list to course-correct before it goes too far in the wrong direction. Many agents will do this automatically in certain situations but sometimes it can't hurt to ask! - -### Refinement Passes - -Agents, like humans, often need multiple passes to polish code. After the initial implementation, use skills like `/code-simplifier` to clean up verbose or overly defensive patterns. Think of it as a code review step before your actual code review to catch the obvious issues before opening a PR. - ### Let the Agent Fetch Context Instead of copying and pasting error messages, give the agent a PR or issue URL and let it fetch the details itself. It can read build failures, status check logs, and PR comments directly using the `gh` CLI. This saves you time and ensures the agent sees the full context. @@ -223,18 +223,6 @@ Instead of copying and pasting error messages, give the agent a PR or issue URL When running multiple sessions, enable terminal notifications so you know when an agent is waiting for input. iTerm2 has built-in notification support, or you can use a custom notifications hook. This lets you context-switch to other work while agents run, without constantly checking back. -### Terminal Setup - -[Ghostty](https://ghostty.org/) is a popular choice for its synchronized rendering, 24-bit color, and proper unicode support. Color-code and name your terminal tabs, one tab per task or worktree. Some people use tmux for this. - -- **Theme:** Run `/config` to set light or dark mode. -- **Newlines:** If you use Claude Code in an IDE terminal, Apple Terminal, Warp, or Alacritty, run `/terminal-setup` to enable shift+enter for newlines (so you don't need to type `\`). -- **Vim mode:** Run `/vim` to enable vim keybindings. -- **Status line:** Run `/statusline` to show model, directory, remaining context, cost, and more below the composer. See the [status line documentation](https://code.claude.com/docs/en/statusline). -- **Voice dictation:** You speak 3x faster than you type, and your prompts get way more detailed as a result (hit fn twice on macOS). - -See the [terminal configuration docs](https://code.claude.com/docs/en/terminal-config) for more. - ## Workflows ### Bug Fixing