We recently launched NASEBANAL API Specs, a developer-facing site that brings together the OpenAPI reference for each of our APIs and a Cookbook of integration recipes that use them, all in one place. In this post, I'd like to lay out the concern behind that launch — a sense of "lost visibility" I've come to feel while using AI coding day to day — and the two efforts it has prompted. I'll close with what lies beyond them: my expectation for the OpenAPI spec as a shared guardrail across in-house, outsourced, and agent development.
The Motivation — The "Unease" I Felt with AI Coding
When you hand development to an AI agent, features get implemented at a startling pace. Convenient as that is, the moment something merely passes a functional check, the instinct to "it runs, so let's ship it now" tends to take the lead.
The problem is that our understanding of the implementation can't keep up with that release velocity. Code that never properly went through review piles up, and the actual state and complexity of the codebase gradually become harder to see. This is not unique to agent-driven work — the same shape arises with offshore development, or any work done by hands other than your own.
That led me to the following thought:
I don't need to trace every last detail. But I do want what state the code ended up in after each PR and Merge to be left behind, as needed, in a form a human can grasp.
As a means of "leaving it in a form a human can grasp," I came to place my hopes in two directions. One is visualization through metrics — taking a bird's-eye view of the state of the code and the development activity as a numeric time series. The other is Spec Driven Development — fixing the contract (the spec) to be exposed externally first, and making the implementation conform to it. My recent work is an attempt to give each of these a concrete form.
Effort #1 — Splitting Out the API Reference, as Groundwork for Contract-Driven Development
The first effort was to split each API's OpenAPI reference out of the product apps and move it to a model where it is managed independently, as the developer-facing site NASEBANAL API Specs. Rendering is powered by Scalar, so you can review each API's spec in the browser. The Cookbook on the same site also collects runnable recipes that use those APIs.
This separation is groundwork for Contract-Driven Development (CDD). Once CDD is functioning, it works directly as a guardrail for AI coding. In particular, I have a strong interest in CDD built on the OpenAPI spec as a contract, with Specmatic generating contract tests and stubs from it.
Why manage the contract independently? When you develop the frontend and backend simultaneously with AI coding, the feature work itself proceeds very smoothly. Yet precisely because both are moving in parallel, a phenomenon arises in which the interface you are meant to expose — the contract — paradoxically becomes harder to pin down. The shape the frontend expects and the shape the backend returns drift apart quietly, without passing through review — the classic case of contract drift.
By carving the OpenAPI spec out as a versioned contract and generating stubs and contract tests from it with Specmatic, the frontend can run end-to-end tests with no live backend. Beyond that, as CDD takes hold, I expect that a new version of an API can be reflected smoothly into the frontend through the contract. At NASEBANAL we are currently rolling out this CDD flow across Account / Recorder / Target in stages. I plan to cover its design motivation, pipeline shape, and how it works in practice in a dedicated post in the near future.
Effort #2 — Making Development Visible: DORA / Code Metrics and Token Consumption
The second effort was to actually apply the "human-graspable" metrics visualization described above to our own development and put it into operation. The concrete procedures are published as runnable recipes in the Cookbook. There are two pillars.
Monitoring DORA / Code Metrics
The first is a pattern that accumulates DORA metrics (deploy count, lead time) and code metrics (LOC, and so on) from GitHub Actions into the Recorder, per merge and daily (recipe). This gives a time-series, bird's-eye view of where "development by others" — including agents and offshore teams — currently stands. Even without tracing every diff, how the size, complexity, and deploy frequency of the code changed with each merge is left in a form a human can read at a glance.
The chart above is real data from a NASEBANAL repository: total LOC on the left axis (orange) and branch density on the right (green). LOC trends up while branch density edges down — a sign that structural cleanup is keeping pace with the codebase's growth.
Note: This particular sample is from the Recorder repository during a stretch with little substantial work, so the chart comes out fairly flat and a bit unbalanced; please read it with that caveat in mind.
Monitoring Token Consumption
The second is a pattern that uses a Claude Code Stop hook to record per-project token consumption into the Recorder (recipe). It visualizes the four values — Input / Output / CacheRead / CacheCreate — as a per-app time series.
Looking at the raw Input / Output, Output (green) climbs into the hundreds of thousands of tokens while Input (red) hugs the baseline. Most of the input is served from the prompt cache, so the raw input tokens that are actually billed stay small.
The cache side is on a roughly 100× larger scale, so it gets its own chart. CacheRead (green) reaches tens of millions of tokens, showing that most of the context is reused from the prompt cache.
To be candid, this one is still at an experimental stage, and there is room to improve both the granularity of the aggregation and how it is interpreted. Even so, I believe analyzing token consumption per app of development will only grow more important for evaluating the ROI of AI development. Claude Code is dominant at present, but should more capable tools emerge, we will need to compare and evaluate them on the same footing — and whether a per-app, per-tool time series of consumption is at hand will, I think, greatly affect the quality of that judgment.
In Closing — Toward Implementing a Shared Guardrail Across In-House, Outsourced, and Agent Development
In the software development to come, I feel that the emergence of agents will prompt a rethink of the division of roles between in-house and outsourced development (including the use of external services). Until now, the options were largely in-house development, domestic outsourcing, and offshore development. In Japan especially, the language barrier and the business customs particular to the local IT industry combined to keep reliance on domestic outsourcing high for a long time. But with the rapid rise of agent-driven development, in some cases the user company itself takes on in-house development powered by agents and orchestrates a kind of teamwork with its outsourced development — a new division of roles that is increasingly being looked to. And the demand to evaluate that mix — its proportions and its merits — with metrics will only continue to rise.
At the same time, if we can put a shared guardrail in place across those very different kinds of contributors — in-house, outsourced, and agent — that translates directly into quality control. As that shared guardrail, I am increasingly drawn to the potential of the OpenAPI spec as a "document that defines the role / contract." Whoever — or whatever — wrote the code, if the contract it must satisfy is the same, we should be able to hold a common quality floor.
To test that hypothesis, I am currently running a quality evaluation that combines Specmatic and other tools. I plan to share those results in detail in the next post. I hope you'll stay tuned.
Software is never finished the moment it ships — as a service, it needs continuous maintenance and improvement. There is much concern these days that AI may lead to layoffs of software engineers; yet for that very reason — in this domain where continuous maintenance is indispensable — I hold out hope that putting agents to work could push forward digitalization that previously went unattended.
In Japan in particular, I feel there remain a great many areas where digitalization is hoped for yet, though entirely feasible technically, has not been realized. Spec-Driven agent development moving such areas forward one step at a time — that is a possibility I would like to keep digging into myself.