# Building with AI Tools

> Create, debug, and publish modules with AI coding tools such as Claude Code.

URL: https://www.trakhound.com/docs/trakhound-framework/ai-tools

AI coding tools such as [Claude Code](https://claude.com/claude-code) can create, debug, and update TrakHound modules from a description of what you need. The Framework gives these tools a well-defined target: every module starts from a template, inherits a base class, has one responsibility, and uses the same interfaces for data, settings, and logging. The Instance handles hosting, security, routing, and deployment, so generated code only needs to contain the logic for your process.

Diagram: Start from a template, whose AGENTS.md tells the AI tool the conventions. Describe the module, let the AI tool write it, run it locally with dotnet run so the tool can fix its own errors, then review the change. Repeat in small steps, then publish a versioned Package, try it on a test Instance in a Zone in Audit mode, and install the approved version in production.

## Why It Works Well

- **Templates** - Each module type has a template with the correct base class, manifest, and project setup, so the AI tool starts from a working project
- **Small modules** - An App, API, Function, or Worker does one thing, keeping each request and each change small enough to review
- **Common interfaces** - Data is read and written through [Services](https://www.trakhound.com/docs/trakhound-framework/services), so generated code does not need connection strings, credentials, or database specific code
- **Local debugging** - Modules run with `dotnet run` against a local Instance, and unit tests run them without one, so the AI tool can build, run, test, and fix its own errors
- **Packages** - Finished modules are versioned Packages, so AI-built tools follow the same review, deployment, and change control as everything else

## 1. Create the Project from a Template

Start every module from a template instead of asking the AI tool to create the project. The template sets up the base class, the `trakhound.package.json` manifest, the `Program.cs` used for local debugging, and instructions for AI coding tools:

```
dotnet new trakhound.app -n MachineStatus
cd MachineStatus
```

See [Quick Start](https://www.trakhound.com/docs/trakhound-framework/getting-started) to install the templates and build your first module.

## 2. Review the Project Instructions

AI coding tools read an instructions file in the project folder to learn its conventions. Every template creates an `AGENTS.md`, read by most AI coding tools, and a `CLAUDE.md` that imports it for Claude Code. It lists the commands to build, run, and publish the module, its files, and the rules for writing that kind of Package, such as reading data only through `Client.Services`, not hard coding paths or credentials, and describing API parameters.

Edit it as the module grows, adding what is specific to your module, such as the Services and collections it uses and what belongs in other modules:

```
## This Module
- Show machine status only. Put data collection in a Worker and processing in a Function
  instead of adding it here.
- Machine status is in the 'machines' Key-Value collection, keyed by machine ID.
- Do not change trakhound.package.json unless asked.
```

> For a repository with several modules, put an `AGENTS.md` at its root as well. Point the AI tool at these docs for details, for example the [Apps](https://www.trakhound.com/docs/trakhound-framework/apps) and [Services](https://www.trakhound.com/docs/trakhound-framework/services) pages.

## 3. Describe the Module

Describe what the module should do in terms of TrakHound concepts: which Services it reads and writes, which Functions or APIs it calls, and what it displays or returns.

```
claude "Create a page that lists every machine in the 'machines' Key-Value collection
with its current status. Refresh every 5 seconds and show Running in green and
Stopped in red."
```

Example requests for each module type:

| Module | Example Request |
| --- | --- |
| [App](https://www.trakhound.com/docs/trakhound-framework/apps) | Create a page that shows open work orders from the `work_orders` Table, with a filter by machine. |
| [API](https://www.trakhound.com/docs/trakhound-framework/apis) | Add a GET endpoint that returns the status of a machine from the `machines` Key-Value collection, and a PUT endpoint that updates it. |
| [Function](https://www.trakhound.com/docs/trakhound-framework/functions) | Create a Function that reads yesterday's part counts from the `parts` Table and writes a daily summary PDF to the `reports` Blob collection. |
| [Worker](https://www.trakhound.com/docs/trakhound-framework/workers) | Create a Worker that subscribes to `machines/+/status` Messages and stores the latest status of each machine in the `machines` Key-Value collection. |
| [Identity](https://www.trakhound.com/docs/trakhound-framework/identity) | Create an Identity provider that authenticates requests using a token stored in the Identity configuration parameters. |

## 4. Run and Debug Locally

Ask the AI tool to build and run the project with `dotnet run`. The module connects to the local Instance at `localhost:8472`, so the tool can see build errors and runtime logs and fix them before you review the result. Use the **Explorer** and **Diagnostics** pages in the Instance's admin UI to check data, API requests, and logs.

To try the module inside the Instance with its routing and security, run `th dev run`, which reinstalls it each time the tool saves a change. Ask the tool to add unit tests with `TrakHound.Testing` too, so it can check its own changes with `dotnet test`. See [Debugging & Testing](https://www.trakhound.com/docs/trakhound-framework/debugging).

## 5. Review the Changes

Review generated code the same way you would review code from a new team member:

- Keep each request small (one page, one endpoint, or one Function at a time) so each change is easy to read
- Check that data is accessed only through `Client.Services`, and that no paths, URLs, or credentials are hard coded
- Check that the module still has a single responsibility, and split it into separate modules if it has grown
- Commit to source control after each working step so changes can be compared and undone

## 6. Package, Publish, and Install

Build the module into a versioned Package and install it on an Instance:

```
th packages dotnet --publish
th packages install MachineStatus
```

Then create a configuration for the Package in the admin UI. Because every Package is versioned, a previous version can be reinstalled with `th packages install <packageId> --version <version>`. See [Packages](https://www.trakhound.com/docs/trakhound-framework/packages) and the [CLI](https://www.trakhound.com/docs/trakhound-framework/cli).

Install new versions on a test Instance first so process engineers can try them before they reach production. See [Development, Test & Production](https://www.trakhound.com/docs/trakhound-framework/environments).

## Building Larger Applications

Split a larger application into several modules and build them one at a time, for example a Worker that collects data, a Function that processes it, an API that exposes it, and an App that displays it. Modules share data through Services and call each other with `Client.Functions.Run` and API requests, so each one can be generated, reviewed, and updated on its own. Engineers from different teams can build their own modules with AI tools and still run them on the same Instance.

## Security and Regulated Environments

- AI coding tools send prompts and code to the tool's provider. Check your organization's policies before using them with sensitive, export controlled, or regulated code and data.
- The AI tool is only used during development. The modules you build, and the data they work with, run on your own Instances.
- Modules do not need database or message broker credentials. These are set by IT in Service configurations on the Instance (see [Services](https://www.trakhound.com/docs/trakhound-framework/services)), so the AI tool never sees them.
- Never give an AI tool production credentials or paste them into prompts or instructions files.
- Identity modules and security profiles apply to AI-built modules the same as any other module.
- Add new modules to a [Zone](https://www.trakhound.com/docs/trakhound-framework/zones) in Audit mode to see exactly which APIs, Functions, Services, and Volumes they reach, then switch to Enforce so they can't reach anything else by accident.
- A Zone's Service Router can send every Service call a module makes to test data while it is being tried on a shared Instance.

## Connecting AI Assistants to an Instance

This page covers using AI tools to *build* modules. To give AI assistants access to the data and Functions *in* an Instance, turn on the Instance's built-in [MCP Server](https://www.trakhound.com/docs/trakhound-framework/mcp-server). AI clients such as Claude can then list and run Functions, read Logs, query Tables, and read Key-Values and Messages, limited by the same security profiles and API keys as everything else.

To let AI assistants use your own module, ask the AI tool to mark the API endpoints that are safe for an agent to call with `[ApiMcpTool]` and to describe their parameters. See [APIs](https://www.trakhound.com/docs/trakhound-framework/apis).

AI coding tools building applications on an Instance's APIs can read its [/llms.txt](https://www.trakhound.com/docs/trakhound-framework/api-catalog#llms-txt), a Markdown index of the APIs they can use, with links to each OpenAPI document.

A module that runs code an AI tool wrote in another language (ex. a Python script) can give that process a [Module Token](https://www.trakhound.com/docs/trakhound-framework/zones#module-tokens), so its calls are made as the module and its Zone still applies.
