ZSpec at Zhihu: One-Person Multi-Platform Development with AI Agents

Problem: Redundant Multi-Platform Development

Traditional mobile development assigns separate engineers per platform (iOS, Android). As product forms expand to Harmony, RN, Flutter, mini-programs, and Web, a single user feature becomes inherently multi-platform. Cross-platform frameworks reduce UI and logic duplication but cannot eliminate platform differences in lifecycle, system capabilities, engineering dependencies, packaging, signing, device debugging, and release processes. The main cost is not writing code multiple times, but the repeated flow of the same requirement across multiple development sites: repeated interpretation, context switching across repos/IDEs/devices, re-verification of behavioral consistency, root-cause analysis of failures, and context recovery after interruptions.

AI Coding Context

JetBrains 2025 Developer Ecosystem Report shows 85% of developers use AI tools, 62% use at least one coding assistant. Agents can assist with entry-point discovery, call-chain understanding, local implementation, engineering commands, and verification evidence gathering. However, Stack Overflow 2025 Developer Survey indicates only 17% of Agent users believe Agents improve team collaboration; "almost correct but not completely correct" remains a major pain point. DORA 2025 AI-Assisted Software Development Report defines AI as an "amplifier" that magnifies both organizational strengths and existing process defects. After code investigation and local implementation are accelerated, the bottleneck shifts from "coding" to "context and collaboration."

Key Questions for Agent Integration

Does the Agent understand the correct requirement?

Is the technical solution grounded in current code facts?

Do multiple platforms share the same product goal while correctly handling platform differences?

After code completion, is there trustworthy runtime evidence?

After interruption, source changes, or verification failure, which step should we resume from?

ZSpec Solution: Reorganizing the Entire R&D Chain

ZSpec is an AI-Agent-oriented R&D workflow and engineering toolset. It does not replace platform expertise but establishes an executable, verifiable, recoverable development site for Agents to continuously advance from requirements through design, implementation, verification, to delivery. For one-person multi-platform, ZSpec unifies product goals, isolates per-platform engineering facts, and keeps code, decisions, and evidence with clear ownership. Humans own goals, key judgments, risks, and final acceptance; Agents handle reusable investigation, implementation, and engineering operations within clear workspace, rule, and authorization boundaries.

Overall Architecture

ZSpec organizes the R&D process into four continuous phases: prepare a working development site, transform requirements into per-platform solutions, complete implementation and verification, converge collaboration results and retain recoverable context. These phases are not extra processes but a reorganization of information scattered across chats, repos, docs, IDEs, and devices. Each phase defines its inputs, artifacts, and pass conditions; when requirements or source code change, the workflow can determine the earliest invalidated stage and resume from there.

The system is grounded in three layers:

Engineering Carrier : ZSpec CLI with Group/Unit workspaces create or restore development sites, prepare source code, modules, branches, and maintain cross-platform organizational relationships.

Agent Runtime Environment : Harness installs scope-appropriate Skills, AGENTS.md, and knowledge bases into the workspace so Agents entering a Group or Unit get correct rules and platform capabilities.

R&D Process & Evidence : Requirements, Context, Spec, Plan, code Diffs, and Agent-device acceptance results carry product goals, engineering facts, technical decisions, execution process, and completion conclusions, making the entire chain traceable, auditable, and recoverable.

Capability Map

ZSpec CLI provides a unified engineering entry covering the full workspace lifecycle. Capabilities are not isolated commands; through workspace identity and structured R&D assets, ZSpec places "workspace, Agent context, R&D decisions, code, acceptance, and delivery" into a single engineering model. When requirements, source code, or verification results change, the workflow judges the earliest invalidated phase and continues from the correct point, avoiding Agents producing code with stale conclusions or requiring a full restart.

ZSpec Workspace: Organizing Multi-Platform Projects

Group/Unit Model

To solve organizational boundaries, ZSpec uses a Group/Unit model separating two fact types:

Group represents a cross-platform requirement, maintaining only shared product goals, scope, business rules, and acceptance criteria.

Each platform corresponds to an independent Unit (e.g., iOS Unit, Android Unit, Harmony Unit, RN Unit).

Each Unit independently stores current code structure, module ownership, platform constraints, technical solution, code changes, and verification results.

The core is "fact ownership":

Group Unified : Product goals & user value; User-visible behavior; Business rules & non-goals; Acceptance criteria; Explicit platform product exceptions.

Unit Independent : Current code structure & Owner; Platform capabilities & constraints; Components, interfaces, state flows; Implementation order & verification methods; Code & runtime evidence.

When a Unit hits a technical constraint, it only revisits its own Context or Spec, not blocking other ready platforms. Only when evidence points to missing shared product rules does the Group Requirements get updated, triggering re-validation for all affected Units.

Multi-Platform Workspace Structure

On the filesystem, a workspace with a modular iOS Unit looks like:

<group>/
├── zspec.json # Group identity & Unit registry
├── AGENTS.md  # Group-level collaboration rules & doc boundaries
├── .agents/skills/ # Union of Unit Skills
├── docs/      # Shared requirements entry
│   └── group/requirements/<topic>.md
│
├── <branch>_ios/  # iOS Unit
│   ├── zspec.json # Unit identity, platform, Git boundaries
│   ├── AGENTS.md
│   ├── .agents/skills/
│   ├── docs/
│   │   ├── context/<topic>.md
│   │   ├── spec/<topic>-spec.md
│   │   └── plan/<topic>-plan.md
│   ├── <iOS main project>/
│   └── <iOS components>/
│
├── <branch>_android/
├── <branch>_harmony/
└── <branch>_rn/

zspec.json records Group/Unit identity, platform, and real engineering boundaries; AGENTS.md and Skills directories provide Agents with scope-specific rules and capabilities; docs link to persistently stored R&D documents. Skills directory adapts to target IDE (.agents/skills/ or .claude/skills/) but Group/Unit fact ownership remains IDE-agnostic.

Three Unit Engineering Structures

Platform type alone doesn't describe a Unit's engineering shape. ZSpec abstracts Units into three structures:

modular : Contains main project, can link component repos. ZSpec configures main_project, supports involved_modules, provides component-to-main build chain.

single : Contains main project, no component module set. ZSpec configures main_project, develops & verifies around single main project.

collection : Multiple independent repos, no unified main project. ZSpec manages by repo collection, skips main-project-centric build flow.

This abstraction lets Group/Unit model unify multi-platform requirements while preserving differences in repo organization, module dependencies, and build methods.

Workspace Lifecycle

Workspaces can be created from new requirements or restored from existing collaboration sites. After entering a developable state, platforms can be incrementally added, and code, Agent capabilities, and R&D docs continuously maintained. Adding a new platform (e.g., Harmony to existing iOS/Android Group) runs zspec new with the same requirement link: ZSpec preserves existing Units' Git and doc states, creates the new Unit, prepares its repos and platform capabilities, and updates Group's Skills union — no full rebuild needed.

ZSpec continuously maintains code baselines, Agent capabilities, and R&D docs. Commands zspec module sync, retarget, renew align collaboration sites, migrate baselines, and start new fix rounds from target baselines. Harness ensures Units continuously receive current platform Skills, AGENTS.md, and knowledge bases, and maintains Group's multi-platform capability union. Group Requirements and Unit Context/Spec/Plan stay connected to long-term doc storage via docs.

For handover, zspec clone <release-or-mr-or-task-or-epic-url> restores repos, dev branches, target branches, MR combinations, shared Requirements, per-Unit Context/Spec/Plan, and doc indexes. It verifies Group registration, real paths, and platform consistency without overwriting existing Units or guessing relationships by directory names. The restored site includes decision rationale and acceptance context, not just compilable code.

Creating a Workspace

For cross-platform requirements with existing Task/Epic, developers run:

zspec new <branch> <task-or-epic-url>

ZSpec shows a terminal platform selector (multi-select). Confirmation auto-creates the workspace. Alternatively, ZSpec Desktop GUI provides a "Start" button to select target platforms (iOS, Android, Harmony, RN). Both CLI and GUI follow the same Group/Unit model and proceed with Harness installation, repo preparation, and module management per Unit engineering structure.

ZSpec Harness: Making Agents Understand Your Workspace

After code and docs are ready, Agents need to understand current platform engineering norms, boundaries, and executable actions. Harness installs these contexts into the correct workspace: Skills provide executable capabilities (Feature, Bugfix, debugging, acceptance), AGENTS.md defines workspace rules and authorization boundaries, knowledge bases supply platform engineering knowledge. Harness focuses on installation according to Group/Unit boundaries and continuous updates when capability sources change.

Three-Layer Harness Structure

Capability Source Layer : Stores real sources of Skills, engineering rules, platform knowledge.

ZSpec Managed Layer (~/.zspec/harness): Syncs Sources, organizes rules and Skills into editions and bundles.

Workspace Installation Layer : Installs only what the current workspace needs per Group/Unit scope.

These layers separate "where capabilities come from", "how they become usable versions", and "where they are finally installed". Multiple workspaces share the same managed capability source without each replicating full resources; Agent contexts stay isolated by platform and scope.

Narrow Scopes: Skills Appear Only Where They Belong

More Skills ≠ stronger Agent. Dumping iOS, Android, Harmony, RN, debugging, release, ops skills into global scope forces Agents to pick from huge candidate sets, causing irrelevant skill triggers, cross-platform experience misapplication, and rule/context interference. Harness installs by scope:

Global scope : Only user-selected general skills; avoid loading full platform suite by default.

Group scope : Installs union of all valid Unit Skills for cross-platform requirement understanding and dispatch.

Unit scope : Installs only shared workflows and current platform's needed skills (e.g., iOS Unit never loads Android/Harmony platform capabilities).

Platform knowledge base : Follows Unit installation, stays out of Group, avoids polluting other platforms' engineering facts.

Thus Agents in Group see cross-platform coordination skills; in a Unit they see that platform's development, debugging, acceptance skills. Skill routing no longer relies solely on model judgment from a massive global list; workspace boundaries narrow candidates first, then Agent selects by task intent. Narrow scope reduces noise, not capability, stabilizing skill calls and keeping "shared product goals" and "platform engineering facts" aligned with Group/Unit boundaries.

Harness Installation & Updates

Installation : Embedded in workspace lifecycle. Running zspec new or zspec clone refreshes local Harness, determines Group's edition, installs Skills/AGENTS.md/knowledge base per platform for each Unit; after Units ready, Group's AGENTS.md and multi-platform Skills union update automatically.

Updates : Every ZSpec update automatically refreshes Harness in all workspaces; no manual per-Group/Unit refresh needed.

ZSpec Workflow: Requirement-to-Acceptance Closed Loop

Single Main Chain from Requirement to Verification

ZSpec structures one requirement development into eight stages. Group forms shared Requirements; each Unit independently completes Context, Spec, Plan decisions, implementation, and verification based on its own code. Stage 7 (Agent-device acceptance) enters per acceptance criteria and authorization, not a mandatory fixed step for every change.

Requirements : What does user need? Scope & observable acceptance? Artifact: Group docs/group/requirements/<topic>.md. Pass: Goals, rules, non-goals, target Units, version, acceptance criteria confirmed.

Context : Current code, Owner, call chains, deps, platform constraints? Artifact: Unit docs/context/<topic>.md. Pass: Source baseline complete, no unhandled product conflicts, Requirements version matches.

Spec : How to implement on this platform? State flows, interfaces, exceptions, compatibility? Artifact: Unit docs/spec/<topic>-spec.md. Pass: Technical direction clear, risks & verification methods understood; high-risk designs reviewed.

Plan : What order to modify which Owners? How to verify incrementally? Artifact: Conversation Plan or Unit docs/plan/<topic>-plan.md. Pass: Modification boundaries, order, dependencies, rollback points, verification methods executable.

Implementation : How to realize confirmed solution with minimal changes? Artifact: Each Unit's code & necessary config. Pass: Changes within approved boundaries, no unauthorized product behavior or engineering scope expansion.

Fresh Quick Evidence : Do changes pass minimal, directly related basic checks? Artifact: Diff, static checks, unit tests, or local build evidence. Pass: Evidence from current source, directly related to this change.

Agent-device Acceptance (on demand) : Do Required acceptance items hold in real runtime? Artifact: Each Unit's acceptance matrix, device evidence, Ledger. Pass: Runtime acceptance required & device flow authorized; all Required items have latest auto evidence or explicit human confirmation.

Delivery : How to archive R&D docs & submit collaboration results? Artifact: Archive, Commit, Push, MR. Pass: Only execute user-explicitly authorized delivery actions.

Plan scales with complexity: single Owner, mature patterns, no migration/sequence risk → skip independent Plan doc; multi-module, complex deps, cross-session recovery → write files, Owners, order, verification, rollback points into Unit Plan.

Before coding, ZSpec confirms target Units, code write boundaries, basic validation methods; if runtime acceptance needed, also confirms App, device, build/install/start/device_qa actions. Code modification authorization does not auto-extend to device ops, Commit, Push, or MR authorization. If only code approved, after basic checks it reports runtime coverage gaps without prompting for device acceptance.

Multi-Platform Independent Progression & Version Control

Shared Requirements use common + platform version for multi-platform baseline:

Shared goals, scope, rules, acceptance, target Units change → common + 1 → All target Units re-validate.

Single platform's product exception changes → Corresponding platform version + 1 → Only invalidates that Unit's downstream conclusions.

Context and Spec record their confirmed Requirements versions. Before entering Spec, Implementation, acceptance loop, and explicit /submit, the current Unit's common + platform version must still match. This versioning lets requirement changes precisely back-propagate: platform constraints affecting only one Unit don't force others to restart; only when shared goals, business rules, or acceptance criteria change does the workflow return to Group to update Requirements.

After shared Requirements ready, Units can parallelize Context evidence gathering and proceed to Spec, Plan, implementation, acceptance at their own pace — no "all Units finish Context before continuing" global barrier. One platform's environment or design issue only rolls back to its earliest invalidated stage; other platforms' validated docs and evidence remain valid.

Recoverability: Resume from Earliest Invalidated Stage

Multi-platform tasks span multiple sessions, repos, delivery nodes. Source code may change, requirements may gain edge conditions, a platform's design may be disproven in acceptance. ZSpec doesn't treat "recovery" as reopening old chat; it first judges what information is invalidated:

Product behavior, scope, acceptance, target platforms change → Requirements

Current behavior, Owner, deps, source facts change → Context

Technical direction, interfaces, state flows, compatibility strategy change → Spec

File boundaries, implementation order, verification orchestration change → Plan judgment

Upstream still valid, implementation incomplete → Implementation

Verification fails → Return to earliest disproven stage

Recovery scope controlled by Requirements versioning: shared rule changes trigger all target Units re-validation; platform exception changes only invalidate that Unit's downstream conclusions. This prevents stale conclusions from propagating further while avoiding full chain restart for a local change. Recoverability also means handover: workspace retains requirements baseline, per-Unit Context, Spec, Plan, verification evidence. New person or Agent resumes from latest still-valid stage, not guessing from lost conversation.

Agent-device Automated Acceptance Loop

In mobile dev, compile success ≠ interaction works; App launch ≠ target page behavior correct. Agent-device is ZSpec's runtime acceptance core: it enters target page on specified real device/emulator, executes operations, reads UI state, and judges via observable assertions — not just launch, screenshot, or log glance.

Around Agent-device, ZSpec adds Acceptance Orchestrator and Test layers. Orchestrator generates acceptance matrix from Requirements, schedules per Unit, maintains Ledger, handles failure backflow. Test handles Build, artifact location/verification, Install, Start, then drives Agent-device via platform debug capabilities.

Acceptance loop supports four entry points: auto-enter from Feature/Bugfix parent flow when conditions met; manual start when boundaries complete; resume with original Unit Ledger after fix/blockage removal; read-only aggregation of existing Ledgers without build/device ops.

Fixed acceptance drive chain: Feature/Bugfix → Acceptance Orchestrator → Test → Platform Debug Capability → Agent-device. Chain is one-way; Test never reverse-triggers acceptance loop; independent /test is a full verification without auto-repair, returns evidence and blocks on failure.

Each platform swaps only the middle platform debug capability: iOS uses ios-debug, Android uses android-debug, Harmony uses harmony-debug, RN resolves real host platform first. Orchestration, Test results, evidence formats stay consistent.

Fresh Quick Evidence, Orchestrator, Test, Agent-device handle basic gating, multi-platform scheduling, runtime env prep, device ops respectively. Four layers keep clear boundaries: basic checks don't replace runtime acceptance; Agent-device doesn't define product expectations; Test doesn't reverse-trigger auto-repair.

Acceptance items come from current Requirements' Acceptance Criteria; Unit Spec can only supplement technical verification, not redefine product expectations. Screenshots or "looks normal" alone cannot prove acceptance; logs only auxiliary evidence. UI acceptance items must form observable assertions on current build, establishing continuous identity chain: source snapshot → build run → build artifact & digest → install receipt → specified device & independent session → Agent-device ops & assertions → Unit Ledger.

Device flow requires independent confirmation of Unit, App, device, account context, acceptance actions, external effects. Code modification authorization does not include App install or device ops; if tool/device/evidence identity chain unavailable, result goes to manual acceptance or block, never packaged as auto-pass.

passed_automated : All Required items have auto evidence on current build → Write Unit Ledger, await multi-Unit aggregation.

passed_with_manual : All Required items pass, but include explicit human confirmation → Write Unit Ledger, await multi-Unit aggregation.

manual_required / blocked : Still needs human confirmation, or env/tools cannot proceed → Retain checklist & blocking evidence, do not declare pass.

repair_required : Requirements, facts, design, or implementation disproven → Return to earliest affected stage, fix, rebuild, re-accept.

Each Unit independently generates acceptance matrix, runs Test, saves Ledger. One Unit blocking doesn't affect other ready Units. Only passed_automated or passed_with_manual enter delivery aggregation; fixes can resume with original Ledger but must rebuild and bind new source/artifact identity to re-verification results. Failure backflow follows "return to earliest disproven stage": unclear product expectations → Requirements; code fact changes → Context; technical direction invalid → Unit Spec; implementation error → Implementation. Thus Agent-device not only automates device ops but plugs runtime evidence back into recoverable R&D chain.

Practice Summary: Principles, Efficiency Gains, Boundaries

Starting from Existing Engineering Systems

In Zhihu's environment, a requirement may involve iOS, Android, Harmony, RN, multiple component repos, engineering norms, device environments, collaboration branches. ZSpec adoption didn't create a new R&D system but transformed existing norms, platform knowledge, collaboration methods, permission boundaries into Agent-understandable engineering context. Five integration points:

Use Yunxiao Task, Epic, MR, Release as stable entry for requirements & collaboration sites.

Group/Unit manage shared product goals, multi-platform boundaries, multi-repo relations.

AGENTS.md, Harness, platform Skills solidify engineering rules, debugging methods, acceptance capabilities.

ZSpec CLI unifies workspace creation, source prep, branch alignment, collaboration recovery, doc archival.

Agent-device connects real-device verification across platforms while preserving human authorization boundaries for device ops and external actions.

Example: "Comment page interaction upgrade" affecting iOS, Android, Harmony. Developer maintains one shared Requirements in Group; three Units independently investigate code, form Context and Spec. Ready platforms implement first; constrained platforms only adjust locally. After device authorization, each Unit completes Agent-device acceptance, then results aggregate. One person manages not three mixed codebases but three independent development sites advancing around same product baseline.

Principles from Practice

Manage facts first, then generation. Without unified requirements and current code evidence, faster generation only amplifies inconsistency.

Share product goals, not platform inferences. One platform's implementation can be a clue but cannot replace another's Context and technical decisions.

Completion must carry current evidence. Basic checks support code conclusions; acceptance items needing runtime evidence must be auto-verified or explicitly handed to human.

Fail back to earliest invalidated stage. When acceptance disproves design, carry evidence backflow instead of stacking local patches.

Workflow scales with complexity. Simple changes compress docs and steps; high-risk, multi-module, or recovery-needed tasks fully expand evidence chain.

Observing Overall Efficiency Gains

Better to measure wait, duplication, rework, recovery costs across the whole R&D chain than Agent-generated lines of code:

Workspace preparation : Time from requirement input to multi-platform engineering ready.

Requirement consistency : Multi-platform repeated clarification count, rework count from understanding gaps.

Context switching : Time spent manually finding commands, norms, Owners, call chains.

Multi-repo collaboration : Manual fetch, rebase, branch switch, push, MR operation counts.

Acceptance efficiency : Required items automation coverage, remaining manual acceptance items.

Issue localization : Time from failure occurrence to clear evidence and failure boundary.

Recovery efficiency : Time to restore site after session interruption, task switch, or personnel handover.

Operational safety : Unauthorized Commit, Push, MR, device ops, release counts.

These metrics are continuous observation directions; don't treat doc count or code generation volume as efficiency outcomes. The real goal is shortening overall cycle from requirement input to multi-platform trusted delivery, verifying whether same requirement reduces repeated flow, and whether one person can stably advance multiple platforms with lower collaboration and recovery cost.

Conclusion: From Faster Coding to Trusted Multi-Platform Delivery

One-person multi-platform is not about one person repeating same work on multiple platforms, but aligning the same requirement once, letting each platform advance independently along its own engineering facts, finally converging into one trusted delivery with evidence.

AI has significantly lowered cost of code investigation, local implementation, engineering ops, but doesn't automatically eliminate multi-platform redundant understanding, platform differences, collaboration waits, verification gaps. When coding is no longer the main bottleneck, overall efficiency hinges on whether R&D context sustains, platform facts stay clear, and implementation results gain trustworthy verification.

ZSpec's value isn't adding another process layer but reorganizing the entire requirement-to-delivery chain. Group unifies product goals; Unit isolates platform facts; Harness gives Agents current workspace rules and capabilities; Requirements, Context, Spec, Plan cement requirements, facts, decisions; Agent-device grounds final conclusions in real runtime evidence. When requirements, code, or verification results change, developers resume from earliest invalidated point, not full restart.

This doesn't weaken platform professionalism but reorganizes multi-platform collaboration: platform differences respected, humans focus on goals, key decisions, risks, acceptance; Agents shoulder reusable investigation, implementation, engineering ops. Ultimately amplified is not just Agent coding speed, but one person's ability to stably advance multiple platforms.