AI Vibe Coding in Practice, Part 3: Turning the SMS Plan into a Spec Baseline

The first two articles documented my conversations with Claude Code about the architecture and product decisions for an SMS suite in CabloyJS.

The first round separated the responsibilities of SMS infrastructure, verification, authentication, and Mock delivery. The second clarified explicit registration, international numbers, real suppliers, and shared Web/Admin identities without automatically granting administrative permissions.

With a plan in place, should the next instruction be to start coding? In this round, I first asked Claude Code to turn the discussion into spec documents.

The prompt was short.

/cabloy-spec-generation I agree with your plan. Please organize it into spec documents.

The point was not to produce a few more Markdown files. It was to turn agreement scattered across a conversation into a planning baseline that could later be checked, broken into increments, and verified.

1. Confirm the document scope before starting implementation

Claude Code did not interpret “I agree” as permission to create business modules. It first checked the repository's planning conventions, existing account planning, Web/Admin sites, and login routes, then stated the scope for this round:

I will create a complete new-suite baseline for Cabloy Basic under repo-specs/cabloy-sms/, with Chinese body text. The scope is:

• Six core documents: README, PRD, SRS, PDP/WBS, test plan, and progress.
• A boundary ADR and a runbook for real SMS supplier integration and acceptance.
• A Gantt chart and burndown chart derived from the complete WBS input; these do not represent schedule commitments or completed progress.
• The agreed plan: explicit SMS registration, international numbers, shared existing Web/Admin sites, and initial delivery of Mock + Alibaba Cloud + Tencent Cloud + Twilio, with Vonage deferred.
• A clear distinction between existing source and proposed capabilities. The ADR starts as Proposed, delivery status starts as not-started, and this approval does not extend to code execution, real SMS sending, or release authorization.

It also identified two constraints from the existing system:

The existing home-user plan excludes usernames and other login identifiers from freely editable profile fields. The new spec will preserve that boundary and state the necessary username-consistency checks, without expanding rename permissions. Supplier accounts, destination enablement, and real test numbers block only acceptance of their respective channels, not independent delivery of the Mock flow.

This was more than a summary of the previous answer. The earlier discussion had examined the relationship between usernames and display names. This round checked existing account planning and confirmed that SMS integration should not quietly broaden profile-editing permissions. Recommendations in a conversation still need to align with boundaries already recorded in the repository.

In the scope confirmation, I selected:

Generate the complete baseline as recommended, using English body text.

Claude Code acknowledged the adjustment:

Understood. I will generate the complete baseline with English body text, while continuing to report in Chinese. I will write only planning files under repo-specs/cabloy-sms/, without running scaffolding, database operations, or real SMS sends.

What follows is therefore the generation of an English spec baseline, not a retrospective on completed SMS functionality.

2. Six core documents, six different questions

“Organize the plan into documents” can easily turn into copying the same architecture description into several files. A more useful approach gives each document a distinct responsibility.

The core set generated in this round was:

Document	Main question
README	Where should readers start? What are the current scope, status, and next step?
PRD	Why build this, and for whom? Which business capabilities belong in the initial release, and which do not?
SRS	What constrains implementation? What contracts govern modules, APIs, security, identities, concurrency, and frontend integration?
PDP/WBS	In what order should delivery happen? What are the dependencies and completion conditions?
Test plan	How will compliance be demonstrated? Which scenarios and evidence are required?
Progress record	What has not started, what has evidence, and which decisions or external conditions remain open?

For example, “SMS login must not automatically create an account” should not appear only once in a chat. It needs to become a product behavior, a system contract enforced at the existing-identity and authentication boundaries, an implementation task, and an acceptance scenario demonstrating that a missing identity does not silently create a user.

These are not six parallel versions of the same story. They describe different layers of the same goal.

From product requirements to acceptance evidence

The baseline links requirements and delivery through explicit identifiers:

PRD → SRS → WBS → ATP
Product requirement → System requirement → Delivery task → Acceptance scenario

The value of these identifiers is not tidy formatting. They help answer:

• Which requirement does this delivery task serve?
• Which task implements a particular security requirement?
• What evidence must support a claim that the task is complete?
• If an acceptance scenario fails, which part of delivery is affected?

Not every planning activity needs an invented runtime test, either. A first-slice boundary decision can be completed through documentary review, but that cannot establish that SMS sending has been verified.

3. Separate architectural decisions from operational procedures

Alongside the six core documents, this round generated a boundary ADR and a supplier operations runbook.

The ADR: record the boundaries without implying approval

An ADR is an architecture decision record. ADR 0001 remained Proposed, recording the proposed responsibility boundaries between SMS transport, verification, identities, and the existing framework.

“I agree to have the documents generated” is not the same as “I approve every technical detail and authorize implementation.” Explicit status prevents a complete-looking plan from being mistaken for unrestricted execution permission.

The supplier runbook: what remains after code integration?

Real SMS integration involves more than SDK calls and parameter mapping:

• Secure configuration of supplier accounts and credentials.
• Approved signatures, templates, or sender identities.
• Enabled destination countries and regions.
• Consenting test numbers, allowlists, and spending limits.
• Handling definitive rejection versus an uncertain timeout outcome.
• Channel disablement, cutover, and rollback.

These procedures belong in a runbook. Real credentials, full phone numbers, and verification codes do not belong in the spec.

The runbook also preserves a key distinction from the previous article: supplier acceptance of a request does not prove that the handset received the message. Adapter mapping can be verified first; live-send and handset-receipt evidence must be obtained separately, once the prerequisites and explicit authorization are in place.

4. External prerequisites block their own branches

During generation, Claude Code clarified how delivery would be divided:

The documents will track foundational sending, verification security extensions, explicit registration/login, Web/Admin integration, and real supplier acceptance as separate delivery items. Supplier accounts, signatures, templates, and country permissions constrain acceptance of the corresponding channels; they do not block independent delivery of the Mock flow.

This is a practical boundary.

If a Twilio destination has not been enabled, the international channel cannot be declared accepted. That does not require every development activity to stop. Mock can still independently exercise the sending contract, phone-and-purpose binding, code consumption, and registration/login flow.

Conversely, a working Mock flow cannot mark Alibaba Cloud, Tencent Cloud, and Twilio as accepted.

This allows a useful increment to move forward without hiding unfinished live-channel requirements in a progress table.

5. One check failed before the final pass

Not every check passed on its first attempt.

The initial planning check found 45 formal definitions, but the documents already referenced two derived charts that had not yet been generated. It reported missing link targets:

complete planning structure failed (45 definitions).
Missing local link target: implementation-gantt.svg.
Missing local link target: implementation-burndown.svg.

The charts were then generated, followed by a fresh planning check and chart-freshness check:

npm run spec:charts -- cabloy-sms
npm run spec:check -- cabloy-sms
npm run spec:charts:check -- cabloy-sms

The final results were:

complete planning structure passed (45 definitions).
checked implementation-gantt.svg and implementation-burndown.svg
(en; 0/10 verified).

The 0/10 verified matters. Generating charts did not manufacture implementation progress. All ten delivery tasks still had not-started status.

The Gantt chart represented task organization and dependencies; the scope-count burndown represented recorded status. Neither was a schedule commitment or a velocity forecast based on actual delivery history.

The planning checker also explicitly stated its limits: it checks static structure, while approval, semantic sufficiency, implementation, and evidence authenticity still require human review. Connected identifiers do not establish that a design is correct. Rendered charts do not establish that a feature works.

6. The recovered completion reply

Below is the final reply from that round, translated into English. Its conclusions and status are preserved; file links have been simplified to document names for readability.

The complete English spec baseline for Cabloy Basic is finished, entirely under repo-specs/cabloy-sms/.

Document entry point

README — planning overview and reading order.

Document	Content
prd.md	Product goals, user journeys, initial and deferred scope
srs.md	provider/clients/scene, verification security, identities and concurrency, Web/Admin integration
pdp-wbs.md	Staged delivery, dependencies, and completion conditions
test-plan.md	12 acceptance scenarios and evidence requirements
progress.md	Initial status, open decisions, and subsequent entry points
ADR 0001	Proposed technical boundaries and decision gates
Supplier runbook	Channel configuration, live-send acceptance, failure handling, and disablement

Two English charts have also been generated: an implementation roadmap and a scope-count burndown.

Key points recorded in the baseline

• Explicit registration: phone number + user-chosen username + registration code; SMS login does not automatically register users.
• International numbers normalized to E.164; Web/Admin reuse existing identities, Passport, and shared sites.
• Initial scope includes Mock, Alibaba Cloud, Tencent Cloud, and Twilio; Vonage is deferred.
• Reuse and safely extend a-captcha, rather than building another OTP system; cover binding, atomic consumption, rate limits, and generic-entry-point bypass risks.
• Mock autofill is allowed only for actual Mock transport, outside production, with explicit enablement; real channels never return codes to the frontend.
• Real-channel accounts, signatures, templates, and country permissions are accepted separately and do not block implementation of the Mock branch.

Check results

• spec:check: passed, with 45 formal definitions and a complete traceability chain.
• spec:charts and spec:charts:check: passed.
• Local-link, whitespace, and machine-local-path privacy checks passed; charts were rendered and inspected.

Only planning generation is complete: the ADR remains Proposed, all 10 delivery tasks are not-started, and there is no runtime or real-supplier acceptance evidence. No scaffolding, dependency installation, database operations, real sends, or commits were performed.

The next candidate is WBS-SMS-10-01: implement scene-driven Mock sending for the verification consumer, proving tenant isolation and production denial. Enter implementation only after the corresponding decisions and execution dossier have been approved through cabloy-spec-execution.

The 45 formal definitions, 12 acceptance scenarios, and 10 delivery tasks are different planning counts—not a set of passing tests. The status above is a snapshot at the end of this generation round, not a statement about later development progress.

7. What this step actually left behind

Looking back at the short prompt, what I wanted was a change in working state: from a plan discussed in conversation to a baseline that could be handed over and verified incrementally.

That transition depends on keeping several boundaries clear:

• Product agreement: what belongs in the initial release, and what does not.
• Technical decisions: which details remain Proposed rather than implicitly approved.
• Delivery tasks: the dependencies and exit conditions for each useful increment.
• Acceptance evidence: the difference between a planned scenario and an actual result.
• Operational authorization: document-generation approval is not permission to write code, reset databases, send paid messages, or release software.

This does not require planning every detail until nothing is unknown. It means giving each unknown an owner and defining a bounded next step.

Once the spec identifies an independently verifiable Mock sending slice, implementation can focus on that slice instead of repeatedly rewriting the entire grand plan. How verification, identities, and frontend flows actually connect is a question for the next stage—answered with code and runtime results.