📝 Originally published in Japanese on Zenn. This is the English version.
Canonical: https://zenn.dev/uya0526_design/articles/satellite4_ai-collaboration

📚 This is satellite article #4 (the finale) in my "Read-Aloud Speed Meter dev log" series. For the whole picture, see the main article.

Where This Sits

The read-aloud speed meter was the first project where I adopted "AI-collaborative development" as an explicit mode. Until then, my learning style was "I write all the code myself; AI is a reviewer." With a contest deadline looming, I stepped one notch further.

This article isn't a technical deep dive — it's a reflection on the development style itself. Three things:

• The reframe from "did you use AI" to "are you the one driving"
• The stumbles I actually hit in AI collaboration, and the patterns I pulled out of them
• Why rejecting an AI suggestion was the single most important thing

💡 This is a record of an ex-Java SE engineer learning TypeScript and Python in public. It's less a technical article and more a reflective, prose-y piece on the development process.

---

I Switched Styles

My learning articles have always run on a rule: I write the code myself; I use AI for hints, spec clarification, and bug spotting. Typing every word myself had learning value.

This time there was a contest deadline, and a huge amount to cover. So I switched into a collaborative mode: AI demonstrates boilerplate (recording, fetch, API Route skeletons), and I handle the conceptual core and the design decisions.

The awkward part was how to disclose that in the article. I'd publicly stated my AI use for code before, but this time I collaborated with AI on the article's outline, structure, draft prose, and even translation. In a contest with money (a prize) on the line, blurring that didn't feel honest.

At first I framed it as "using AI is no different from accepting an IDE's autocomplete." But that was inaccurate.

• Autocomplete ≈ word/line-level completion
• This time ≈ delegating outline, structure, drafting, and translation → closer to co-building the article with an editor

Since the degree of involvement was far greater than autocomplete, blurring it as "I used AI a little" was wrong. I reconsidered: writing concretely what I delegated to AI and what I did myself is both more honest and more self-protective.

---

The Reframe: Not "Did You Use AI" but "Are You the One Driving"

The most useful lens for thinking about disclosure was this.

The question isn't "did you use AI" — it's "are you the one driving."

This comes from Zenn's community guidelines emphasizing "a place where people drive the dissemination of information," and listing two conditions for "the person is driving":

1. The author verifies the content before publishing
2. The author embeds their own experience and insight into the content

Against this standard, disclosure isn't a "confession" — it's "presenting evidence that I meet the bar." This project:

• made its own decisions on tech selection (consolidating on Next.js), the evaluation-algorithm design, and the architecture (BFF)
• verified the code's behavior with Vitest, starting with calculateMetrics
• holds first-hand information like audio-format compatibility, the divide-by-zero guard, and the hunt for threshold bases

In that sense, I'm on the side that meets the "driving" conditions. So disclosure isn't scary — it's actually a presentation of strengths.

I summarized the axis of disclosure like this:

The thinking is mine, the wording is AI-assisted, and I verify all of it.

I decided the tone too: no apologetic register — state the facts plainly. Writing apologetically signals "the author thinks AI use is a problem," which invites the very criticism I want to avoid. Laying out facts calmly conveys "this is just a normal professional workflow."

---

A Collection of Stumbles — Where Collaboration Got Stuck

AI collaboration is fast, but it isn't unconditionally correct. Here are representative cases I hit, isolated, and fixed myself. The technical details are in satellite #1 (AmiVoice) and satellite #2 (Haiku).

① I got AmiVoice's auth method wrong

I assumed REST API auth meant an Authorization header. AmiVoice's synchronous HTTP puts the API key in the multipart u field. I read the official manual myself, hit it with curl, and finally corrected it.

→ Lesson: For external APIs, take a two-stage check — official spec + actual testing (curl) — not just AI's explanation.

② The mapper returned empty (result vs results)

In the mapper that reshapes raw JSON, the first version referenced result.tokens (singular) and got nothing. The correct path was results[0].tokens (a plural array).

→ Lesson: This was preventable if I'd looked at the raw JSON with curl first. See the real data with your own eyes before implementing.

③ I rejected 0 as falsy

In an input check I wrote if (!value), which rejected a stagnation rate of 0 (which is actually a good result). Since 0 is falsy, an existence check needs ?? "" or === undefined.

→ Lesson: "no value" and "value is 0" are different things. This was the same as distinguishing Java's Optional/null check from an empty/0 check.

④ The prompt cache wasn't working

I thought I'd cheapened a static prompt with caching, but it didn't reach Claude Haiku's 4,096-token minimum, so it wasn't working at all. I only noticed by looking at usage.

→ Lesson: "The official feature exists" and "it helps in my use case" are different. Check the preconditions too.

⑤ Haiku mentioned punctuation that wasn't in the input

Even for short reads with no punctuation, Haiku tacked on "take a breath at the punctuation." Fixing the prompt still doesn't prevent it 100%.

→ Lesson: Written in the prompt ≠ obeyed. Instruction and verification are separate; check against real data whether it was obeyed.

---

The Thread Through the Stumbles: "A Passing Test ≠ Behaving as Intended"

Lined up, most of the stumbles had the same structure:

• The mapper "worked," but referenced the wrong place (②)
• The validation "passed," but wasn't meant to reject 0 (③)
• The cache was "configured," but wasn't working (④)
• The prompt was "written," but wasn't obeyed (⑤)

These are all gaps between "what I thought I did" and "what's actually true." The lesson I'd grasped in an earlier project — "a passing test ≠ behaving as intended" — applied directly in AI collaboration too.

In AI collaboration, because code comes out fast and plausible-looking, this "thought vs. actual" gap gets harder to see. Which is exactly why the value of keeping your verification in code and real data went up, I feel. The more something is AI-generated, the more you confirm it yourself.

---

The Most Important Thing Was the "Rejection"

What stuck with me most in AI collaboration wasn't what AI wrote — it was rejecting an AI suggestion.

When I used the openings of The Tale of the Heike and Hōjōki as read-aloud scripts, AI's review explained the two works' attributions backwards (mixing up author and work). I verified against the literature, judged my implementation correct, and rejected AI's correction.

A small event, but it was a moment of demonstrating "the person is driving" through action. Don't swallow AI's suggestions whole; verify domain knowledge against primary sources. That accumulation underpins the trustworthiness of both the code and the article. When I write "I verified AI's suggestions" in the contest disclosure, this isn't abstract — it's a concrete episode I can tell.

---

A "Pattern" for Collaboration Took Shape

Across several projects, my own pattern for collaboration came into view.

AI is good at "lining up options," "producing a first draft," and "pointing out rough spots"; I take on "choosing," "deciding," and "confirming." Concepts by my own hand, boilerplate to AI — but always demanding an explanation and understanding it before taking it in. This split was the realistic solution that let me balance the deadline with learning.

☕ Java comparison: It's close to designing a detailed interface yourself and delegating part of the implementation. The design is mine, the initial implementation is AI's — which is exactly why I read the delegated parts myself, rewrite them if needed, and keep the final responsibility.

---

Wrapping Up

A reflection on building a real product through AI collaboration. Three points:

1. The question is not "did you use AI" but "are you the one driving." Disclosure isn't a confession — it's presenting evidence of being the one driving.
2. Most stumbles are gaps between "what I thought I did" and "what's actual." "A passing test ≠ behaving as intended" was the thread through AI collaboration too.
3. The most important thing was, more than what AI wrote, rejecting an AI suggestion. Verify domain knowledge against primary sources.

Working with AI makes development faster. But the faster it goes, the more "thought-I-did" creeps in. So don't let go of the driving. Keep the thinking and the verification with yourself, and collaborate on the wording and the boilerplate — that, for me right now, is "AI-collaborative development where the person is driving."

That completes the series. You can trace the app's whole picture, each implementation, and the basis for the metrics from here:

• Main article — Measuring read-aloud with AmiVoice timestamps (overview)
• Satellite #1 — Implementing AmiVoice synchronous HTTP
• Satellite #2 — Claude Haiku coaching design and the prompt swamp
• Satellite #3 — The rationale behind the metrics
• 📦 https://github.com/uya0526-design/reading-speed-meter

---

This article is a record of development and writing done with AI assistants (Claude / Cursor). The design, tech-selection, and verification decisions were made by the author. I collaborated with AI on the article's outline, structure, and draft prose, and reviewed and revised every line before publishing.