3.29 · Guides
Building a backend with an AI agent and Hinoki¶
What exists today (2026-11-13), what it guarantees, and what it does not.
1. Start a project an agent can work in¶
uv run hinoki new shop --dir ~/projects # lower-case letters and digits only
cd ~/projects/shop && uv sync && uv run pytest
The generated project contains a health route, rules that are already on (HNK-ACC-001 actions name an access policy and HNK-ACC-002 a permission, HNK-API-001 and HNK-API-002 responses are concrete Schema types, HNK-API-003 lists are paginated, HNK-TXN-001 writes use a transaction, HNK-SCH-001 fields such as password_hash never appear in a response schema, HNK-SCH-002 request text has a length limit); the two model rules HNK-DB-001 and HNK-DB-002 are written in rules.py as comments to turn on with your first model, because a model rule that matches no model fails the check, AGENTS.md (commands, conventions, and where the agent's authority ends), CLAUDE.md (a pointer to it), .mcp.json (starts the read-only development MCP) and hinoki-rules.toml (the owner's exceptions). The project's own tests pass and hinoki check exits 0; the test suite of this repository generates a project and runs both on every change.
2. What the agent gets¶
AGENTS.md: the same conventions this repository uses: public unless protected on purpose,atomic=Truefor writes,Schemaclasses in responses, no model responses, explicit relation loading, create from aSchemawith server values winning, migrations as reviewed SQL.- The development MCP (
hinoki mcp, read only):inspect_project(the real registry),list_rules,explain_action(signature,Schematypes, access, diagnostics for one action),check_project(rule diagnostics with stable IDs and locations)explain_error(what a validation or HTTP error code means and how to fix it) andpropose_model(source text for a model, its In/Patch/OutSchemaclasses and CRUD actions from a field list; returned, never written). The tools never write code, rules or waivers. - Optional
run_scenario, off by default:hinoki mcp --scenarios readlets the agent send GET/HEAD/OPTIONS/QUERY requests to the app in-process and see status and body;--scenarios writeallows any method. It runs the real handlers and the app's lifespan even inreadmode (a GET handler may write), so it is not annotated read-only and should only face a disposable database. A failed startup is reported without its message (which may hold a connection string); the details go to the server's stderr. Only the owner can switch it on; the agent cannot. - Errors that say what to do: validation errors list every problem with its path and a stable code;
explain_errormaps a code to its meaning and fix; a registration error names the action and parameter.
See the development MCP guide for tool arguments, result shapes and the effectful scenario option.
Optional agent skills¶
hinoki new shop --skills (or the prompt in a terminal) and hinoki skills install in an existing project write four Markdown playbooks under .claude/skills/: hinoki-add-endpoint, hinoki-fix-rule, hinoki-review-api and hinoki-test-api. Each one tells an assistant which MCP tool or CLI command to run and which changes belong to the owner (never hinoki-rules.toml). They are off by default; see hinoki skills.
Checking a change against clients¶
uv run hinoki openapi shop.main:app --output openapi-baseline.json # released version
uv run hinoki openapi shop.main:app --breaking-against openapi-baseline.json
Exit status 1 lists each change that would break an existing client (removed operations or response fields, new required request input, narrowed enums, changed types); see openapi.
Generated request bodies¶
hinoki.ai.samples.request_cases(app.openapi()) returns one RequestCase per operation with a JSON body: a method, a path, a body that satisfies the declared schema, and invalid, a list of (description, body) pairs that each break one rule (wrong type, missing property, too long, below a bound, and so on).
from hinoki.ai.samples import request_cases
for case in request_cases(app.openapi()):
... # send case.body: expect 2xx; send each body in case.invalid: expect 422
The generator reads only the OpenAPI document. It raises CannotSample for a schema it cannot build a value for (such as a regular-expression pattern), and a path with parameters needs real values before it is sent. Use a disposable database and synthetic data.
3. The loop¶
- The agent asks the MCP for the project (
inspect_project) to read the registered routes and models. - It makes a small change (a model, a
Schema, an action). - It runs
pytest,ruff,mypyandhinoki check. - A rule violation is a stable ID, a location and an explanation. The fix is to change the code. Waivers are the owner's decision:
hinoki-rules.tomlis read by the tools, never written, and a waiver needs a reason, an owner and a bounded target. An agent that edits it to pass a check is violatingAGENTS.md; the framework cannot stop someone with write access, it makes the change visible in review (put the file under CODEOWNERS).
4. Limits (what this does not do)¶
- The development MCP describes and checks a project; to let an agent use a running app, publish selected actions with
hinoki.ai.mcpapp.expose_as_mcp(allowlist, caller's own credentials, reads by default; see Application MCP). - The development MCP was exercised with the official
mcpPython client (tests/mcpclient/verify.py: initialize,tools/list,tools/call); other clients are untested. propose_modelis a starting point: it can scope rows to an owner (owner=), paginates the list and takesunique_together, but business rules, state transitions and relations beyond the owner are yours to write.- Rules decide declarations, not what a function body does; static import rules read the project's own files and report dynamic imports as unverifiable.
- The guide was verified twice: by generating a project and running its tests and
check, and by having a fresh agent add an owner-scopedBookmarkresource from the generatedAGENTS.mdalone. That run found the problems now fixed (the framework path in the generatedpyproject.toml, the missing test client, the database variable forcheck, the missing recipe,explain_errorgaps,propose_modelwithout ownership). It is one run by one agent, not a benchmark.