02｜Engineering Practice for Connecting Claude Code to Crazyrouter#

This is the second article in the Crazyrouter Claude Code series. This article focuses on engineering practice for connecting Claude Code to Crazyrouter, with an emphasis on the official Claude Code best practices.

Unified integration convention: Claude Code / Anthropic native clients use ANTHROPIC_BASE_URL=https://cn.crazyrouter.com; OpenAI-compatible SDKs, HTTP requests, and frontend/backend applications use base_url=https://cn.crazyrouter.com/v1.

What This Article Covers#

• Who it is for: developers who are using Claude Code, preparing to integrate domestic models, or want to unify team calls through Crazyrouter.
• What you will learn: how to configure environment variables based on the Crazyrouter documentation, organize workflows, and avoid the /v1/v1/... issue caused by an incorrect Base URL.
• Recommended preparation: first create a separate API Token in the Crazyrouter Console, then follow the Claude Code integration documentation to complete the basic setup.

Official Claude Code Best Practices#

Introduction#

Claude Code is a command-line tool for agentic programming.

As an internal experimental project, Claude Code gives Anthropic engineers and researchers a more native way to integrate Claude into their programming workflows.

Claude Code is intentionally designed to be low-level and unopinionated, providing access close to the raw model without enforcing a specific workflow.

This design philosophy creates a powerful tool that is flexible, customizable, scriptable, and secure.

Although it is powerful, this flexibility introduces a learning curve for engineers who are new to agentic programming tools—at least until they develop their own best practices.

This document outlines general patterns that have proven effective, both for Anthropic's internal teams and for external engineers using Claude Code across a wide range of codebases, languages, and environments.

Nothing in this list is fixed or universally applicable; treat these recommendations as a starting point. We encourage you to experiment and find what works best for you!

Customize Your Setup#

Claude Code is an agentic programming assistant that automatically pulls context into prompts. This context gathering consumes time and tokens, but you can optimize it by tuning your environment.

Create a CLAUDE.md File#

CLAUDE.md is a special file that Claude automatically pulls into context when starting a conversation. This makes it an ideal place to document:

• Common bash commands
• Core files and utility functions
• Code style guidelines
• Testing instructions
• Codebase conventions, such as branch naming, merging, rebasing, and so on
• Development environment setup, such as pyenv usage and which compilers work
• Any project-specific quirks or warnings
• Any other information you want Claude to remember

There is no required format for the CLAUDE.md file. We recommend keeping it concise and human-readable. For example:

You can place the CLAUDE.md file in several locations:

• The root directory of the codebase, or wherever you run claude (the most common usage). Name it CLAUDE.md and check it into git so you can share it across sessions and team members (recommended), or name it CLAUDE.local.md and add it to .gitignore
• Any parent directory of the directory where you run claude. This is most useful for monorepos: you might run claude from root/foo and have CLAUDE.md files in both root/CLAUDE.md and root/foo/CLAUDE.md. Both files will be automatically pulled into context
• Any subdirectory of the directory where you run claude. This is the inverse of the above case; when you work on files in a subdirectory, Claude pulls in the CLAUDE.md file on demand
• Your home folder (~/.claude/CLAUDE.md), which applies it to all of your claude sessions. When you run the /init command, Claude automatically generates a CLAUDE.md file for you.

Tune Your CLAUDE.md File#

Your CLAUDE.md file becomes part of Claude's prompt, so it should be carefully refined like any prompt you use frequently. A common mistake is adding a lot of content without iterating on whether it works. Take the time to experiment and determine what produces the best instruction-following behavior from the model.

You can manually add content to CLAUDE.md, or press # to give Claude an instruction, which it will automatically incorporate into the relevant CLAUDE.md. Many engineers frequently use # while coding to record commands, files, and style guidelines, then include changes to CLAUDE.md in commits so their teammates can benefit as well.

At Anthropic, we occasionally run CLAUDE.md files through a prompt improver and often tune instructions, such as adding emphasis like "important" or "you must," to improve adherence.

Manage Claude's Allowed Tools List#

By default, Claude Code requests permission for any operation that may modify your system: file writes, many bash commands, MCP tools, and so on. We intentionally designed Claude Code with this conservative approach to prioritize safety. You can customize the allowlist to permit additional tools that you know are safe, or to allow potentially unsafe tools that are easy to revert, such as file edits and git commit.

There are four ways to manage allowed tools:

• Select "Always allow" when prompted during a session.
• Use the /permissions command after launching Claude Code to add or remove tools from the allowlist. For example, you can add Edit to always allow file edits, Bash(git commit:*) to allow git commits, or mcp__puppeteer__puppeteer_navigate to allow navigation using the Puppeteer MCP server.
• Manually edit your .claude/settings.json or ~/.claude.json (we recommend checking the former into source control to share it with your team) .
• Use the --allowedTools CLI flag for session-specific permission settings.

If You Use GitHub, Install the gh CLI#

Claude knows how to use the gh CLI to interact with GitHub, including creating issues, opening Pull Requests, reading comments, and more.

If gh is not installed, Claude can still use the GitHub API or an MCP server, if you have installed one.

Reproducible Project: Claude Code Operation Prompt#

Or run the command to install it: winget install --id GitHub.cli

gh login authorization: gh auth login to obtain a GitHub token

Give Claude More Tools#

Claude can access your shell environment, where you can build collections of convenience scripts and functions for it, just as you would for yourself in day-to-day development.

It can also use more advanced tools through MCP and REST APIs.

Use Claude with bash Tools#

Claude Code inherits your bash environment, giving it access to all of your tools.

Although Claude understands common utilities such as unix tools and gh, it will not know about your custom bash tools without instructions:

1. Tell Claude the tool name and usage examples
2. Tell Claude to run --help to view the tool documentation
3. Document commonly used tools in CLAUDE.md

Using Claude with MCP#

Claude Code is both an MCP server and a client. As a client, it can connect to any number of MCP servers to access their tools in three ways:

• In project configuration (available when you run Claude Code in that directory)
• In global configuration (available across all projects)
• In a checked-in .mcp.json file (available to anyone working in your codebase). For example, you can add the Puppeteer and Sentry servers to your .mcp.json, so every engineer working in your codebase can use them out of the box.

When using MCP, it is also helpful to start Claude with the claude --mcp-debug flag to identify configuration issues.

See the official documentation:

Managing Your Servers#

After configuration, you can manage your MCP servers with the following commands:

Example: Monitoring Errors with Sentry#

Authenticating with Remote MCP Servers#

Many cloud-based MCP servers require authentication. Claude Code supports OAuth 2.0 for secure connections.

1 Add a server that requires authentication

2 Use the /mcp command in Claude Code

In Claude Code, use the command:

Then follow the steps in your browser to sign in.

Using Claude Code as an MCP Server#

You can use Claude Code itself as an MCP server that other applications can connect to:

You can use this feature in Claude Desktop by adding this configuration to claude_desktop_config.json:

Using Custom Slash Commands#

Copyable Project: Project Creation Prompt#

Copyable Project: GitHub Issue Prompt#

For repetitive workflows — debugging loops, log analysis, and so on — store prompt templates as Markdown files inside the .claude/commands folder. When you type /, they become available through the slash command menu. You can check these commands into git so they are available to the rest of your team.

Custom slash commands can include the special keyword $ARGUMENTS to pass parameters from the command invocation. For example, here is a slash command you can use to automatically pull and fix GitHub issues:

Try Common Workflows#

Claude Code does not enforce a specific workflow, giving you the flexibility to use it your own way.

Within that flexibility, several successful patterns for using Claude Code effectively have emerged in our user community:

Explore, Plan, Code, Commit#

This versatile workflow works well for many problems:

1. Ask Claude to read relevant files, images, or URLs, providing either general guidance ("read the files that handle logging") or specific file names ("read logging.py"), but explicitly tell it not to write any code yet.

   1. This is the part of the workflow where you should consider heavy use of subagents, especially for complex problems. Telling Claude to use subagents to verify details or investigate specific questions it may have, especially early in the conversation or task, often preserves context availability without sacrificing efficiency.

2. Ask Claude to make a plan for solving a specific problem. We recommend using the word "think" to trigger extended thinking mode, which gives Claude additional compute time to evaluate alternatives more thoroughly. These specific phrases map directly to increasing thinking budget levels in the system: "think" < "think hard" < "think harder" < "ultrathink". Each level allocates a larger thinking budget to Claude.

   1. If the result of this step looks reasonable, you can ask Claude to create a document or GitHub issue that records its plan, so that if the implementation (step 3) is not what you want, you can reset back to this point.

3. Ask Claude to implement its solution in code. This is also a good place to ask it to explicitly verify that its solution is reasonable as it implements different parts of the solution.

4. Ask Claude to commit the result and create a pull request. If needed, this is also a good time to have Claude update any README or changelog to describe the work it just completed.

Steps 1–2 are critical — without them, Claude tends to jump straight into coding a solution. While that is sometimes exactly what you want, asking Claude to research and plan first significantly improves performance on problems that require deep upfront thinking.

Write Tests, Commit; Code, Iterate, Commit#

This is Anthropic's favorite workflow for changes that can be easily verified with unit tests, integration tests, or end-to-end tests. Test-driven development (TDD) becomes even more powerful with agentic programming:

1. Ask Claude to write tests based on expected input/output pairs. Be explicit that you are doing test-driven development, so it avoids creating mock implementations, even for functionality that does not yet exist in the codebase.

2. Tell Claude to run the tests and confirm that they fail. It is usually helpful to explicitly tell it not to write any implementation code at this stage.

3. Ask Claude to commit the tests to git when you are satisfied.

4. Ask Claude to write code that passes the tests, instructing it not to modify the tests. Tell Claude to continue until all tests pass. Claude usually needs several iterations to write code, run tests, adjust the code, and run the tests again.

   1. At this stage, you can ask it to use an independent subagent to verify that the implementation is not overfitted to the tests.

5. Ask Claude to commit the code to git after you are satisfied with the changes.

Claude works best when it has a clear target to iterate toward — a visual design mockup, test cases, or some other type of output. By providing expected outputs such as test cases, Claude can make changes, evaluate the result, and improve step by step until it succeeds.

Write Code, Screenshot the Result, Iterate#

Similar to the testing workflow, you can provide Claude with visual input:

• Give Claude a way to take browser screenshots (for example, using the Puppeteer MCP server, an iOS simulator MCP server, or by manually copying/pasting screenshots into Claude).
• Provide Claude with visual input by copying/pasting or dragging and dropping images, or give Claude the path to an image file.
• Ask Claude to implement the design in code, take a screenshot of the result, and iterate until its output matches the mockup.
• Ask Claude to commit when you are satisfied. Like humans, Claude’s output often improves significantly through iteration. The first version may be good, but after 2–3 iterations it usually looks much better. For best results, give Claude tools that let it inspect its own output.

Safe YOLO Mode#

You can use claude --dangerously-skip-permissions to bypass all permission checks and let Claude work uninterrupted until it finishes. This works well for workflows such as fixing lint errors or generating boilerplate code.

Allowing Claude to run arbitrary commands is risky and can lead to data loss, system damage, or even data exfiltration—for example, through prompt injection attacks. To minimize these risks, use --dangerously-skip-permissions inside a container without internet access. You can follow this reference implementation using Docker Dev Containers.

Codebase Q&A#

When working with a new codebase, use Claude Code to learn and explore. You can ask Claude the same kinds of questions you would ask another project engineer while pair programming. Claude can intelligently search the codebase to answer general questions, such as:

• How does logging work?
• How do I create a new API endpoint?
• What does async move { ... } on line 134 of foo.rs do?
• What edge cases does CustomerOnboardingFlowImpl handle?
• Why do we call foo() instead of bar() on line 333?
• What is the Java equivalent of line 334 in baz.py?

At Anthropic, using Claude Code this way has become a core part of our onboarding workflow. It has significantly shortened ramp-up time and reduced the burden on other engineers. No special prompting is required—just ask, and Claude will explore the code to find the answer.

Using Claude with git#

Claude can handle many git operations effectively. Many Anthropic engineers use Claude for more than 90% of their git interactions:

• Searching git history to answer questions such as “What changes were included in v1.2.3?”, “Who owns this particular feature?”, or “Why was this API designed this way?” It helps to explicitly prompt Claude to inspect git history when answering these kinds of queries.
• Writing commit messages. Claude automatically reviews your changes and recent history so it can consider all relevant context when writing the message.
• Handling complex git operations, such as reverting files, resolving rebase conflicts, and comparing and porting patches.

Using Claude with GitHub#

Claude Code can manage many GitHub interactions:

• Creating pull requests: Claude understands the abbreviation “pr” and will generate an appropriate commit message based on the diff and surrounding context.
• Implementing one-off fixes for simple code review comments: Just tell it to fix the comments on a PR—or give it more specific instructions—and then push the result back to the PR branch.
• Fixing failed builds or lint warnings.
• Triage and organize Open Issues by asking Claude to loop through open GitHub Issues.

This lets developers automate routine tasks without having to remember how to use the gh command line.

Using Claude with Jupyter notebooks#

Researchers and data scientists at Anthropic use Claude Code to read and write Jupyter notebooks. Claude can interpret outputs, including images, and provides a fast way to explore and interact with data.

There is no fixed prompt or workflow here, but our recommended workflow is to open Claude Code and the .ipynb file side by side in VS Code.

Before presenting to colleagues, you can also ask Claude to clean up or aesthetically improve a Jupyter notebook.

Specifically asking it to “make the notebook or data visualization look good” often helps remind it that it is optimizing for a human viewing experience.

Optimize Your Workflow#

The following recommendations apply to all workflows:

Be specific in your instructions#

Claude Code’s success rate improves significantly with more specific instructions, especially on the first attempt. Giving clear direction up front reduces the need to correct course later.

For example:

| Bad | Good | | Add tests for foo.py | Write new test cases for foo.py that cover the edge case where the user is logged out. Avoid using mocks. | | Why does ExecutionFactory have such a weird api? | Look at the git history for ExecutionFactory and summarize how its api evolved. | | Add a calendar widget | Look at how existing widgets on the home page are implemented, and understand the patterns and how the code and interfaces are separated. HotDogWidget.php is a good example to start with. Then, following the pattern, implement a new calendar widget that lets users select a month and page forward/backward to choose a year. Build it from scratch, and do not use any libraries beyond the ones already used in the codebase. |

Claude can infer intent, but it cannot read your mind. “Specific instructions” help Claude better meet your expectations.

Give Claude images#

You can add images for Claude in the following ways:

• Paste screenshots (pro tip: on macOS, press cmd+ctrl+shift+4 to take a screenshot to the clipboard, then press ctrl+v to paste it. Note that this is not the usual cmd+v used for pasting on macOS, and it does not work remotely.)
• Drag and drop images directly into the prompt input.
• Provide the file path to an image.

This is especially useful when using design mockups as reference points for UI development, and when working with visual charts for analysis and debugging.

If you do not add visual content to the context, it can still help to explicitly tell Claude that visual appeal is important.

Mention the files you want Claude to inspect or modify#

Use tab completion to quickly reference files or folders anywhere in the codebase, helping Claude find or update the right resources.

Give Claude URLs#

Paste specific URLs into the prompt for Claude to fetch and read. To avoid permission prompts for the same domain, such as docs.foo.com, use /permissions to add the domain to your allowlist.

Correct course early and often#

Although auto-accept mode (toggle with shift+tab) lets Claude work autonomously, you will often get better results by being an active collaborator and guiding Claude’s approach. You can get the best results by thoroughly explaining the task to Claude at the start, but you can also correct Claude’s direction at any time.

These four tools help with course correction:

• Ask Claude to make a plan before coding. Explicitly tell it not to write code until you confirm that its plan looks good.
• Press Escape to interrupt Claude at any stage—thinking, tool calls, or file edits—while preserving context so you can redirect or expand the instructions.
• Double-press Escape to jump back in history, edit a previous prompt, and explore a different direction. You can edit the prompt and repeat until you get the result you are looking for.
• Ask Claude to undo changes, usually together with option #2 so you can take a different approach.

Although Claude Code sometimes solves a problem perfectly on the first attempt, using these course-correction tools usually produces better solutions faster.

Use /clear to keep context focused#

During long sessions, Claude’s context window can fill up with irrelevant conversation, file contents, and commands. This can degrade performance and sometimes distract Claude. Use the /clear command frequently between tasks to reset the context window.

Use checklists and scratchpads for complex workflows#

For large tasks with multiple steps or that require exhaustive solutions—such as code migrations, fixing a large number of lint errors, or running complex build scripts—improve performance by having Claude use a Markdown file, or even a GitHub Issue, as a checklist and working scratchpad.

For example, to fix a large number of lint issues, you can do the following:

1. Tell Claude to run the lint command and write all resulting errors, including file names and line numbers, into a Markdown checklist.
2. Instruct Claude to resolve each issue one by one, checking it off after fixing and verifying it, then moving on to the next one.

Pass data to Claude#

There are several ways to provide data to Claude:

• Copy and paste it directly into your prompt, which is the most common method.
• Pipe input into Claude Code, for example, cat foo.txt | claude, which is especially useful for logs, CSVs, and large data.
• Tell Claude to pull data through bash commands, MCP tools, or custom slash commands.
• Ask Claude to read files or fetch URLs, which also works for images.

Most of the time, you will use a combination of these methods. For example, you can pipe in a log file, then tell Claude to use tools to pull additional context for debugging the log.

Automate Your Infrastructure with Headless Mode#

Claude Code includes Claude Code overview - Anthropic and can be used in non-interactive contexts such as CI, pre-commit hooks, build scripts, and automation. Use the -p flag with a prompt to enable headless mode, and use --output-format stream-json for streaming JSON output.

Note that headless mode does not persist across sessions. You must trigger it for each session.

The -p parameter in Claude Code is headless mode (non-interactive mode). Usage is as follows:

Basic syntax:

This mode is especially useful for script automation and CI/CD workflows.

Use Claude for Issue Classification#

Headless mode can support automation triggered by GitHub events, such as when a new issue is created in your repository. For example, the public Claude Code repository uses Claude to inspect incoming new issues and assign appropriate labels.

Use Claude as a Code Reviewer#

Claude Code can provide subjective code review beyond what traditional code inspection tools can detect, identifying issues such as typos, outdated comments, and misleading function or variable names.

Go Further with a “Multi-Claude Collaboration” Workflow#

Beyond using Claude independently, some larger applications that fit this scenario involve running multiple Claude instances in parallel:

Have One Claude Write Code; Use Another Claude to Validate It#

A simple but effective approach is to have one Claude write code while another reviews or tests it. Similar to working with multiple engineers, it can sometimes be useful to have separate contexts:

1. Use Claude to write code
2. Run /clear or start a second Claude in another terminal
3. Have the second Claude review the first Claude’s work
4. Start another Claude (or run /clear again) to read the code and review feedback
5. Have this Claude edit the code based on the feedback

You can do something similar for tests: have one Claude write tests, then have another Claude write code that passes those tests. You can even let Claude instances communicate with each other by giving them separate scratchpads and telling them which one to write to and which one to read from.

This separation usually produces better results than having a single Claude handle everything.

Use Multiple Checkouts of the Codebase#

Instead of waiting for Claude to finish each step, many engineers at Anthropic do the following:

1. Create 3–4 git checkouts in separate folders
2. Open each folder in a separate terminal tab
3. Start Claude in each folder to work on different tasks
4. Rotate through each Claude’s progress and approve or reject permission requests

Use git Worktrees#

This approach works especially well across multiple independent tasks and provides a lightweight alternative to multiple checkouts. Git worktrees allow you to check out multiple branches from the same repository into separate directories. Each worktree has its own working directory and isolated files while sharing the same Git history and reflog.

Using git worktrees lets you run multiple Claude sessions simultaneously on different parts of a project, with each one focused on its own independent task. For example, you might have one Claude refactor your authentication system while another builds a completely unrelated data visualization component. Because the tasks do not overlap, each Claude can work at full speed without waiting for the other’s changes or dealing with merge conflicts:

1. Create a worktree: git worktree add ../project-feature-a feature-a
2. Start Claude in each worktree: cd ../project-feature-a && claude
3. Create additional worktrees as needed (repeat steps 1–2 in new terminal tabs)

Copyable Project: Prompt Example#

• Use a consistent naming convention
• Maintain one terminal tab for each worktree
• If you use iTerm2 on Mac, set up notifications so you get alerted when Claude needs attention
• Use separate IDE windows for different worktrees
• Clean up when finished: git worktree remove ../project-feature-a

Use Headless Mode with Custom Tools#

claude -p (headless mode) integrates Claude Code programmatically into larger workflows while leveraging its built-in tools and system prompt. There are two main patterns for using headless mode:

1. Fan-out: Process large migrations or analyses (for example, analyzing sentiment across hundreds of logs or processing thousands of CSVs):

   1. Have Claude write a script to generate a task list. For example, generate a list of 2k files that need to be migrated from framework A to framework B.
   2. Loop through the tasks and programmatically call Claude for each one, giving it a task and a set of tools it can use. For example: claude -p "Migrate foo.py from React to Vue. When finished, you must return the string OK if successful, or FAIL if the task failed." --allowedTools Edit Bash(git commit:*)
   3. Run the script multiple times and refine your prompt to get the desired results.

2. Pipeline: Integrate Claude into an existing data or processing pipeline:

   1. Call claude -p "<your prompt>" --json | your_command, where your_command is the next step in the processing pipeline
   2. That’s it! JSON output helps provide structure for easier automated processing.

For both use cases, the --verbose flag is helpful for debugging Claude calls. We generally recommend turning verbose mode off in production for cleaner output.

---

• Previous: Article 01
• Next: Article 03
• Configuration docs: Connect Claude Code to Crazyrouter
• API address guide: Base URL and /v1 usage
• One-click configuration script: Crazyrouter Claude Code one-click configuration script

Start Connecting to Crazyrouter#

If you are ready to connect Claude Code, domestic models, or your own applications to Crazyrouter through one unified entry point, follow this order:

1. Go to the Crazyrouter console, create a dedicated API Token, and manage permissions separately by project or team.
2. For Claude Code, use the root domain: https://cn.crazyrouter.com; for OpenAI-compatible SDKs, use: https://cn.crazyrouter.com/v1.
3. When you need to automatically check the environment or quickly write configuration, use the Crazyrouter Claude Code one-click configuration script.
4. If debugging fails, check the console logs first, then verify the API Endpoint guide. Pay special attention to whether an extra /v1 was added to the Base URL. When you need to evaluate model costs or choose a different model, check the Crazyrouter pricing and models page first, then add your frequently used models to the Token whitelist.