Claude Code: A Complete Local Workflow for Agents published: false

Claude Code is good at changing code. It is less reliable when the work includes running a stack: starting services, waiting for them, reading their logs, and stopping them cleanly. TDK CLI gives it a local stack it can control through structured commands, so the agent checks the running system instead of guessing at it.

This is a workflow guide. It describes a setup and the reasons behind each part. It is not a report of results from a production system.

The layers

A working setup has four layers, from the bottom up:

1. The stack. A project with service.json files, run by tdk up.
2. The interface. The tdk mcp server, which exposes the stack as tools.
3. The rules. Project instructions that tell the agent how to use the tools, and what it must not do.
4. The guardrails. Limits on destructive actions, enforced outside the model's judgement.

Build them in that order. A rule file is no use if the stack does not start.

Layer 1: the stack

Create a project and its services:

tdk project --yes
tdk resource api --type backend -y
tdk resource web --type frontend -y

Check that the host can run it, and read the plan before the first start:

tdk doctor --json
tdk up main --dry-run

Do this yourself before you hand anything to an agent. A stack that does not start by hand will not start under an agent either.

Layer 2: the MCP connection

tdk mcp runs a Model Context Protocol server over standard input and output. It exposes six tools: doctor, up, down, status, logs, and resource_list. Each runs the matching command in JSON mode.

Connect it from the project folder. The working directory must be the folder that contains .tdk/project.json. For Codex the config is a project-scoped entry with command = "tdk", args = ["mcp"], and cwd set to the project. For Claude Code, follow the agent tooling guide; I have not checked its exact steps against a running install.

Keep the number of servers small. Each one adds tools the agent must choose between, and a few well-described tools work better than many overlapping ones.

Layer 3: the rules

Project instructions tell the agent what the stack is, how to start it, and what counts as done. Keep them short and specific. A good set includes:

• The start procedure. Call doctor, then up, then poll status until readiness is true.
• The stop condition. Readiness true, or a named failure with its logs.
• The failure branch. If a service fails, read its logs with a small tail, report the error line, and stop rather than retrying blindly.
• The boundaries. No editing of generated files under .autogenerated/. Change service.json or the generator instead.

Instructions that describe a failure you have actually seen are more useful than general advice. Add a rule when something goes wrong, and say why.

Layer 4: the guardrails

Rules are advice. Guardrails are enforced. Claude Code supports hooks, which run commands at defined points, so a check can block an action regardless of what the model decides. Use them for the actions you cannot undo: deleting volumes, resetting data, or changing production configuration. Keep those with a person.

The stack's own checks also act as guardrails. Drift checks block a start when a generated file was hand-edited, and doctor stops the agent when the host cannot run the stack at all.

Model choice

Not every step needs the largest model. Reading status and logs is routine work. Planning a change to a service's dependencies is harder. Match the model to the step, and check the cost of each run before you scale it. The right split depends on your usage, so measure it rather than assuming.

Failure modes

The stack never reaches ready. Check doctor first, then status. A stuck pending often means a dependency has not started.

up returns, but nothing runs. up returns before readiness. The agent must poll. An agent that reports success after up alone has skipped the check.

A generated file blocks the start. The message names the file. The fix is upstream, not in the output.

Two stacks fight over ports. Run tdk down on the old one. A stack left running holds ports, and a new up may refuse to start while an old Tilt answers.

The agent retries a failing start in a loop. Set a limit in the instructions: after a fixed number of attempts, stop and report.

A first session

1. Start the stack by hand with tdk up, and confirm tdk status --json shows readiness.
2. Stop it with tdk down.
3. Connect the MCP server from the project folder.
4. Ask the agent for one outcome: "Start the API and check it is ready, then show the last fifty log lines for the API."
5. Watch the calls: doctor, up, status, then logs if needed.
6. Add the rule that matters most to your project, and only after you have seen the failure it prevents.

Summary

Claude Code works best with a stack it can start, check, and stop through structured tools. TDK CLI provides the stack and the tools. Project instructions and guardrails keep the agent inside the lines you have drawn. Build the layers in order, and add rules from real failures rather than from guesses.