Work with AI Agents
An agent can turn a requirement into a Tegata (手形). It cannot take on the accountability for what that Tegata permits.
That boundary is what makes an agent useful here. The output you review is a specification, not enforcement code scattered through the application. Ninka checks and compiles that specification; it does not decide whether the requirement behind it was correct.
1. Give the agent the Ninka workflow
npx ninka-authz init
init creates AGENTS.md, or appends a Ninka section when the file exists without one. The generated rules tell coding agents to keep authorization in Tegata, compile after policy changes, use the generated Consumer Projection at the application boundary, and surface interpretation choices for review.
If an existing AGENTS.md already contains the Ninka section, init leaves that section untouched. The file is therefore the instruction surface your agent actually sees, not a version-synchronized copy that Ninka silently refreshes. When an upgrade changes a command or workflow named in those rules, review the checked-in section as part of the upgrade.
Ninka does not maintain a separate hidden authorization instruction channel for the agent.
2. Let the agent author the specification
Give the agent the authorization requirement and the application context it needs to map that requirement onto subject, action, resource, conditions, and relationships.
The output to review is the Tegata, not generated authorization branches scattered through application code.
When the requirement requires interpretation, the authoring process should record that interpretation in audit.ambiguities. For example, “their own documents” may require choosing which subject and resource attributes define ownership.
audit is review context; it does not change the authorization decision. See Tegata and Tegata Schema for the exact model.
If the project uses a closed-world Vocabulary, undeclared roles, actions, resource types, and configured attributes are compile errors. That prevents an agent from introducing a new project term without the vocabulary change appearing explicitly in the diff.
3. Use diagnostics as feedback, not approval
Compile the proposed Tegata:
npx ninka-authz compile
Schema and Sekisho diagnostics can identify the structural and semantic problems Ninka knows how to detect. An agent can use those diagnostics to revise its proposal.
A successful compile does not mean the authorization requirement has been approved or correctly interpreted. It means the proposal passed the checks and compilation steps that ran successfully.
4. Review before accepting the change
The accountability boundary is the human review of the authorization specification. Compare the requirement with the Tegata, including its allow/deny scope, conditions, relationships, and recorded ambiguities.
Authorization Reference and generated validation provide supporting evidence. They do not replace that review. See Review Authorization.
Ninka does not store a local “human approved” state. Approval belongs to the surrounding development and change-control process — for example, review of the Tegata diff in a pull request.
5. During migration, require an explicit boundary report
When an agent introduces Ninka into an existing application, the Tegata diff may not represent every authorization behavior that existed before migration.
Require the agent to state:
- what moved to Ninka;
- what authorization remains elsewhere;
- what was intentionally left unchanged;
- what it could not classify confidently.
That report is review evidence, not a Ninka-validated completeness proof. For parity testing and the authority switch, see Migrate from OPA.