Coding agents

Tenchi gives coding agents deterministic inspection, previewable generation, structured diagnostics, and one complete validation command. An MCP-aware agent can access those operations directly through the Tenchi MCP server; an agent with filesystem and shell access can use the equivalent CLI workflow.

You remain in control because contracts, use cases, ports, and composition stay in ordinary Python files. The agent inspects evidence, edits those files directly, and runs the same checks you use locally and in CI.

Give an agent a Tenchi task

Generated applications include an AGENTS.md, so most agents will discover the local rules automatically. For an explicit first instruction, adapt this prompt:

Read AGENTS.md before editing. Run `uv run tenchi map` for the affected feature
and inspect its diagnostics and unresolved references. Explain the intended
files and relationships before changing them. Preview any generated structure
with `uv run tenchi make --dry-run`. Implement the change without hiding
explicit wiring, then run `uv run tenchi check`. If a contract changed, run the
OpenAPI compatibility diff before updating its snapshot. If an application
tool changed, run the tool compatibility diff before updating `tools.json`.
Finish with `uv run tenchi verify --base-ref <historical-ref> --json` and report
the receipt with the files changed.

If you already know the feature, include its name in the task so the agent can start with uv run tenchi map --feature <name> --json instead of loading the complete application graph.

What Tenchi provides

Tenchi's documentation is also published as /llms.txt for compact navigation and /llms-full.txt for the complete guide.

Use the recommended working loop

1. Read the local rules

Start with the generated AGENTS.md. It describes the application's file layout, allowed dependency direction, explicit composition points, error and authorization conventions, and the commands that define done.

Tell the agent to follow those repository instructions ahead of generic framework advice; your application may add stricter local conventions.

2. Map before reading broadly

uv run tenchi map --json
uv run tenchi map --feature notes --json
uv run tenchi map --feature notes \
  --kind contract,route,use-case,policy,port,adapter --json

The complete map combines source declarations with composed API routes, operational tasks, background jobs, and application tools. A feature projection retains directly connected shared and cross-feature nodes, giving an agent a bounded starting context without hiding dependencies that cross the feature directory.

Inspect these fields before editing:

• nodes identify concepts and their source declarations. Runtime-bound kinds such as contracts, routes, jobs, tasks, tools, use cases, and adapters become registered when composition reaches them; source-only declarations remain declared.
• edges explain ownership, route bindings, dependencies, authorization, implementations, and feature tests. Evidence points to the source that supports each relationship.
• confidence is exact when the relationship is directly proven and inferred when it follows a documented naming convention.
• diagnostics embeds the current doctor findings.
• unresolved records relationships the analyzer could not prove. Treat these as missing context, not as permission to assume the dependency is absent.

Node IDs, result keys, and diagnostic codes are stable within the declared schema_version. If your tooling parses the JSON directly, check that version before relying on the rest of the result. Tenchi snapshots the JSON Schema for every structured CLI result and MCP tool input and output in CI. Additive changes may retain the current version; breaking or unknown changes require a new version and preserve the older baseline.

3. Preview generated structure

uv run tenchi make feature notes --dry-run --json
uv run tenchi make use-case notes create_note --dry-run --json

Dry runs perform the same naming and conflict validation as a real generation without writing files. The result lists every planned path and the explicit wiring steps that remain app-owned.

After accepting the preview, run the command without --dry-run. Generators create files but do not rewrite route or infrastructure modules. The agent must make those composition changes in the application files, where you can review them.

4. Edit through the application boundaries

Follow the application architecture rather than placing code where it is merely convenient:

• Contracts own the HTTP boundary.
• Plain async use cases own behavior.
• Pure policies own authorization decisions.
• Feature-owned protocols define infrastructure needs.
• Adapters implement those ports under app/infra/.
• Server modules explicitly compose routes, contexts, hooks, and concrete adapters.

If the graph and the task disagree, inspect the source evidence and unresolved references before expanding the edit. tenchi map is an orientation tool, not a substitute for reading the definitions that will change.

5. Validate once, completely

uv run tenchi check --json

Check runs every step even after one fails, so you receive a complete repair list in one pass. Each step reports its command, exit code, duration, bounded standard output and error output, and whether either stream was truncated.

Treat ok: false as unfinished work. Do not stop after fixing only the first failed step, and do not silently weaken Ruff, Pyright, pytest, doctor, or the OpenAPI and application-tool snapshots to make the aggregate pass.

6. Compare boundary changes historically

For a contract change, compare before replacing the snapshot:

uv run tenchi openapi \
  --routes app.server.routes:api_routes \
  --title my_app \
  --diff openapi.json

uv run tenchi openapi \
  --routes app.server.routes:api_routes \
  --title my_app \
  --diff-ref origin/main \
  --snapshot openapi.json

Breaking and unknown changes fail closed. A baseline from the merge base, previous push, or previous release remains meaningful even when the branch also updates its committed snapshot. See OpenAPI and compatibility for the complete workflow.

For an application-tool change, use the parallel workflow:

uv run tenchi tools --diff tools.json
uv run tenchi tools \
  --diff-ref origin/main \
  --snapshot tools.json

This catches removed tools, narrower inputs, wider outputs, newly possible application errors, and less-safe annotations before an agent replaces the evidence. See Application tools for the complete compatibility rules.

7. Produce the completion receipt

After reviewing and accepting any snapshot updates, verify the finished tree against the same historical point:

uv run tenchi verify --base-ref origin/main --json

The receipt contains the resolved commit, complete check result, application summary, diagnostics, unresolved relationships, and both compatibility reports. It passes only when every check passes, the map has no diagnostics or unresolved relationships, and neither boundary contains a breaking or unknown change.

verify does not replace the diff-before-write review. It proves that the finished tree—including accepted snapshot updates—still agrees with the historical contract. Use the pull request base, previous push, or previous release instead of the branch's current commit.

Choose the right command

Human and JSON modes represent the same operation. Use JSON when another tool will make a decision; use human output when a person is reviewing the work in a terminal.

Know when to inspect the source yourself

The application map is source-backed and conservative. Python permits dynamic imports, factories, decorators, and runtime mutation that static analysis may not be able to prove. Tenchi reports unresolved relationships rather than inventing certainty, and inferred edges remain visibly different from exact ones.

The map also does not prove business correctness. An agent still needs to read the relevant contract, use case, policy, port, and tests, then rely on the full validation loop.

Continue with the coding-agent MCP guide to connect a client, the CLI reference for every command option, or stability and releases for the compatibility guarantees around these result schemas.