Let the Agent Fly: How kiro’s Spec-Driven Loop Turns “Documentation Absolutism” into Velocity

Let the Agent Fly: How kiro’s Spec-Driven Loop Turns “Documentation Absolutism” into Velocity

Reality check: Management demands assurance & documentation; engineers need speed.

Bridge: kiro emits three auditable artifacts every run — Spec, Plan, Trace — giving managers confidence without slowing agents down.

Result: Evidence you can ship. Fewer debates about “how to prompt”; more focus on outcomes.

My Manager: “So, practically speaking—if we lock down the specs and have humans navigate, that’s when AI can show its real value, right?”

Me: “Well, you could say that… but the point is speed. With AI-assisted coding, you can move at an overwhelming pace. Sure, we sometimes give it a big-picture heading. But the pilot and co-pilot have switched seats—humans aren’t in the cockpit anymore.”

My Manager: “Could you document how to brief an agent so it produces good code?”

Me: “Are you serious? Really serious? There are tricks—some people report Claude Code performs better if you tell it to ‘go all out.’ But models evolve daily, and if something is truly useful, it’ll get baked into the editor anyway. Do we really need a document compiling all that?”

My Manager: “Then how can you claim the finished product’s quality is assured?”

Me: “Honestly, there aren’t many programmers who can out-implement an AI agent!”

kiro was a ray of hope for persuading my stubborn manager—because it leaves a paper trail. Documentation, documentation, documentation… why are they so in love with documentation…?

I do get where they’re coming from. In our industry (true story), to fix a single character in an output filename, we first have to open an issue—in Excel— and then ask for managerial instruction! It’s documentation absolutism.

I understand the fear of not knowing what’s happening. A reckless AI agent can cause problems—wandering off in odd directions, bolting on features no one asked for, or pip install-ing dependencies without oversight (risky for commercial use). But above all, I believe I’m the most foolish one here. A bug you ship after 10 hours and a bug you ship after 30 minutes are still the same bug.

(If you’re working closely with customers and touching commercial logic, that level of caution may be unavoidable. But that’s not the case here—these are internal tools!)

Maybe that’s a defeat for programmers.

My personal defeats aside, kiro helped convince management because it produces solid documentation. Documentation. Their beloved, beloved do-cu-ments!!

And most conveniently—it’s in English! We Japanese love documentation, but if the docs are in English, you can sometimes slip past the managerial gaze (perhaps they aren’t reading it anyway?). Ahem… that’s not kiro’s essence, of course.

kiro’s spec-driven development seems to have sparked real excitement and is starting to spread as a core concept for AI coding. With it, you get evidence, an alibi, and a way to sidestep reluctant managers. That’s also why I can take part in this hackathon!

The kiro Approach: Spec-Driven AI Coding

The tension isn’t “AI good vs. AI bad.” It’s speed vs. assurance. kiro resolves this with three first-class artifacts every time work is run:

spec.kiro.md — Ground Truth of Intent
Scope, constraints (security, licensing), interfaces, and acceptance criteria.

plan.kiro.yaml — Decomposition & Guardrails
Task graph with ownership (agent/human), stop/ask points, and built-in checks (lint, license, secrets, tests).

trace.kiro.log — Provenance & Evidence
Prompts, tool calls, diffs, test results, timestamps, commit hashes, tags.

These files make the work reviewable and auditable without slowing the agent.

Minimal, Copy-Pastable Templates
1) spec.kiro.md

Spec:

Problem

• One-sentence goal and target users.

Scope

• In scope:
• Out of scope:

Interfaces & Contracts

• CLI/API/Files, inputs/outputs, error modes.

Constraints

• Security/compliance, licenses, performance budgets, offline/network rules.

Acceptance Criteria

• Given/When/Then scenarios or explicit CLI checks.

Test Strategy (High-Level)

• Unit, integration, smoke; data fixtures.

2) plan.kiro.yaml
version: 1
tasks:

• id: t1_bootstrap
  intent: "Create project skeleton"
  owner: agent
  inputs: [spec.kiro.md]
  outputs: ["src/", "README.md"]
  checks: ["lint", "license_scan"]

• id: t2_core_logic
  owner: agent
  depends_on: [t1_bootstrap]
  checks: ["unit:fast", "security:secrets"]

• id: t3_cli_wireup
  owner: agent
  depends_on: [t2_core_logic]
  checks: ["smoke", "contract_tests"]

• id: t4_human_review
  owner: human
  depends_on: [t3_cli_wireup]

guardrails:
lint: eslint
license_scan: fossy
security: trufflehog
rollout:
strategy: "canary-internal"
fallback: "revert-to-prev-tag"
stop_ask:

• "Any new networked dependency or license change"

3) trace.kiro.log (sample excerpt)
[12:03:11] prompt_hash=... tool=init_repo args={}
[12:04:22] git diff -- src/main.py (+87 -0)
[12:05:10] unit:fast PASS (18/18)
[12:06:02] contract_tests FAIL: 1
[12:06:45] fix applied; contract_tests PASS
[12:07:00] tag v0.2.1

How to Brief the Agent (No “Secret Prompt” Needed)

Use a stable structure, not magic words:

Anchor on the Spec: Always pass spec.kiro.md; ask the agent to restate acceptance criteria.

Constrain Outputs: “Only touch files listed in plan.kiro.yaml.”

Stop/Ask Points: Pause on networked deps or license changes.

Tests Are Gates: Merge only if acceptance checks pass; include failing logs in trace.

Starter prompt

You are an implementation agent. Use spec.kiro.md as the ground truth.
Produce plan.kiro.yaml with explicit tasks, guardrails, and stop/ask points.
Execute the plan and emit trace.kiro.log with prompts, diffs, and test outputs.
Do not install networked dependencies or change licenses without pausing to ask.

A Review Flow Managers Actually Like

Spec review: “Is this what we intend?”

Plan review: “Are guardrails sufficient?”

Trace spot-check: “Did the work follow plan and pass tests?”

Tag & release: Spec + passing Trace = record of release.

Benefits

Deterministic acceptance.

Policy hooks (license/security) as checks.

Reproducible tags/hashes.

Clear audit answers: Intent? Method? Proof?

Risks & Mitigations
Risk Mitigation
Agent scope creep Tight “Out of scope,” file allow-list, codeowners.
Dependency drift Stop/Ask on installs; pin versions; scan licenses.
Flaky tests Separate unit:fast vs e2e:slow; gate on stable tiers.
“Prompt rot” Keep prompts tiny; rely on Spec/Plan structure, not slogans.
Why This Works in “Documentation Absolutism” Cultures

You don’t bolt docs on at the end — docs are the work product:

Spec = signed intent

Plan = auditable method

Trace = evidence pack

Engineers keep velocity. Managers get assurance. Everyone can sleep.

Appendix A — Suggested Layout
.
├─ kiroad/
│ ├─ spec.kiro.md
│ ├─ plan.kiro.yaml
│ └─ trace.kiro.log
├─ src/
├─ tests/
└─ README.md

Appendix B — Acceptance Snippets

• tool --in A.json --out B.json exits 0 and writes valid JSON.
• 10k records < 3s on M2 Air.
• No network calls; no license changes from MIT deps.

P.S. I’m job-hunting. I have a cat. I’m not leaving Japan. I’ll talk to any place willing to let me use Claude Code’s Max plan for both work and personal projects.

To my manager: I don’t want to write user manuals anymore. I’m considering a career move. If you’ll subscribe to Claude Code’s Max plan, I’ll reconsider.