# Using Claude Code with CDK

[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's official CLI tool for working with Claude directly in your terminal. When paired with the **TRAY CDK GUIDE.md** file, it becomes a powerful assistant for building, testing, and deploying Tray CDK connectors.

## What is TRAY CDK GUIDE.md?

`TRAY_CDK_GUIDE.md` is a comprehensive reference file designed specifically for Claude Code. It contains:

* Complete CLI command reference for `tray-cdk`
* End-to-end development flows
* Project structure details
* Authentication configuration patterns
* HTTP and composite operation examples
* Input/output configuration with UI annotations
* Testing strategies
* Deployment procedures
* Troubleshooting tips

When placed in your project as a `CLAUDE.md` file, Claude Code automatically reads it at the start of every conversation, giving it full context about CDK development patterns and conventions.

[Download TRAY CDK GUIDE file](https://tray.ai/documentation/files/cdk/TRAY_CDK_GUIDE.txt)

> **Warning:** The file is downloaded with a `.txt` extension. If you download it manually, rename it to `CLAUDE.md` before placing it in your project root.

## Prerequisites

1. **Claude Code** installed on your machine. Follow the [official installation guide](https://docs.anthropic.com/en/docs/claude-code) .
2. **Tray CDK CLI** installed:

```bash
npm install -g @trayio/cdk-cli
```

3. An existing CDK connector project, or create one:

```bash
tray-cdk connector init my-connector -i
```

## Setup

### Download TRAY CDK GUIDE.txt

Download the guide file into the root of your CDK connector project and rename it to `CLAUDE.md`:

```bash
cd my-connector
curl -o CLAUDE.md https://tray.ai/documentation/files/cdk/TRAY_CDK_GUIDE.txt
```

> **Info:** Claude Code looks for a file named `CLAUDE.md` in the root of your project directory. By saving the guide as `CLAUDE.md`, Claude Code will automatically load it as context for every session.

### Launch Claude Code

Navigate to your connector project and start Claude Code:

```bash
cd my-connector
claude
```

Claude Code will automatically detect and read the `CLAUDE.md` file when the session starts. You can verify this by asking Claude about CDK concepts — it will have full knowledge of the CLI commands, project structure, and development patterns.

## Example workflows

### Creating a new operation

```text
> Add a new HTTP operation called "list_users" that calls GET /api/v2/users
  with pagination support
```

Claude Code will:

1. Scaffold the operation directory with `input.ts` , `output.ts` , `handler.ts` , and `handler.test.ts`
2. Configure the HTTP handler with the correct endpoint
3. Set up pagination parameters in the input schema
4. Write a matching test

### Adding authentication

```text
> Set up OAuth2 authentication for this connector using the "my-service"
  Tray service
```

Claude Code will update `auth.ts` and `connector.json` with the correct OAuth2 configuration referencing your Tray service.

### Debugging a failing test

```text
> The test for get_contact operation is failing with a 401 error.
  Help me fix it.
```

Claude Code will review the test setup, check auth mocking, and suggest fixes based on CDK testing patterns.

### Deploying

```text
> Deploy this connector to the EU region
```

Claude Code will run the appropriate `tray-cdk` deploy commands with the correct region flag.

## Keeping the guide up to date

The `TRAY_CDK_GUIDE.md` file is versioned alongside the CDK documentation. To update to the latest version:

```bash
curl -o CLAUDE.md https://tray.ai/documentation/files/cdk/TRAY_CDK_GUIDE.txt
```

## Tips

* **Be specific** — Tell Claude Code exactly what third-party API you're integrating with and what operations you need.
* **Share API docs** — If you have the third-party API documentation, share relevant endpoints so Claude Code can generate accurate handlers.
* **Run tests incrementally** — Ask Claude Code to run `npm test` after each change to catch issues early.
* **Use composite operations wisely** — If Claude Code suggests a composite handler, it's likely because the operation requires multiple API calls or data transformations.