Skip to main content

Work with AI Agents

Ninka assumes no particular model or vendor — bring your own AI coding assistant. The agent writes the Tegata (手形), the compiler checks it, you approve the diff.

1. Generate the agent rules​

npx ninka init

init writes the AGENTS.md your agent follows when it touches authorization (appended if AGENTS.md already exists without a Ninka section):

  1. Express authorization as a Tegata, not inline if code.
  2. Run npx ninka compile after changing a Tegata.
  3. Call only check() from lib/authz.ts.
  4. Report interpretation assumptions in audit.ambiguities.
  5. Declare vocabulary in authz/vocabulary.json before using new words.
  6. Mark loggable attributes with audit: true.

2. The agent records its assumptions​

When a requirement is ambiguous, the agent writes the judgment call into the non-compiled audit block so it surfaces in review:

"audit": {
  "source_text": "Members can edit their own documents.",
  "ambiguities": [
    {
      "code": "assumed_interpretation",
      "message": "\"their own\" is relationship(subject.user_id = resource.owner_id). Co-owned documents assumed not to exist.",
      "related_rules": ["allow-member-access-own-document"]
    }
  ]
}

3. The Sekisho corrects the agent​

npx ninka compile runs the Sekisho (関所), which rejects semantically dangerous policies with one-line, prescriptive errors. The agent fixes its own Tegata and recompiles — usually without you:

error: rule "allow-member-access-own-document" is unreachable — deny rule
"deny-locked-document" subsumes it. Narrow the deny or remove the allow.

4. You approve the diff​

Review only the Tegata diff and the ambiguity notes. Approval attaches to the fingerprint (tegata_hash); the same Tegata compiled with the same version of ninka-authz always produces byte-identical output, so approving the fingerprint approves the executing code.

See also​