miniapp-product-dev

name	miniapp-product-dev
description	小程序 / Taro / 微信小程序 / 支付宝小程序 / 抖音小程序 / 小程序上线审核 → implement, debug, test, and ship mini-program client features: pages, state, API integration, auth, sharing, platform capabilities, review, and device verification. Triggers also include "重构这个小程序页面/组件(局部)", "refactor a mini-program page/component".

Miniapp Product Dev

Use this skill for mini-program client engineering and platform delivery. It covers product-facing miniapp work across WeChat, Alipay, Douyin/TikTok, Baidu, and similar host platforms. It does not own general product strategy, backend service architecture, or visual design rules.

Framework Scope

Primary framework target: Taro (React-based multi-platform mini-program framework). Apply this skill's recipes assuming Taro unless the task states otherwise.

Adjacent frameworks recognized but not the default target:

• uni-app / Remax / kbone / mpvue: recipes here usually apply with framework-equivalent substitutions; verify before assuming behavior.
• Native WeChat / Alipay / Douyin / Baidu mini-program: host-platform contracts (config, capabilities, review, release) carry over; framework-specific code mechanics (JSX/hooks vs WXML/WXSS, lifecycle hooks, runtime APIs) require native-platform substitution.
• Embedded H5 inside a mini-program webview: this skill owns the mini-program shell, bridge contract, host capabilities, and review/release evidence; the H5 React/Vue page belongs to web-react-dev (or the relevant web skill).

If the team adopts a non-Taro framework as a new primary, the skill scope must be re-declared rather than letting Taro recipes silently apply to mismatched runtimes.

For evaluating whether Taro is the right choice for a given project (vs native, uni-app, Remax/kbone, or splitting per-platform), read references/framework-choice.md. Taro is the current default but not a permanent decision — re-evaluate when the project's target-platform set, design-system divergence, or maintenance signals change materially.

Maturity Baseline

The current baseline is vendor-spec + framework-canonical, not mature confirmed: host-platform guidelines, Taro documentation/examples, and canonical Taro UI libraries (taroify, NutUI-Taro, tdesign React mapping). No production-quality miniapp portfolio has been observed end-to-end. Apply positive rules as defaults and anti-patterns as guardrails, and mark them confirmed only after a correction-free real feature delivery.

Existing team codebases do not automatically supply positive rules: production use proves distribution, not quality. Until audited end-to-end against this skill or piloted through one real feature with a skill-extraction-workflow retrospective, label them quality-unverified per references/source-evidence-map.md. Use this skill from the start and feed lessons back through extraction, not silently copy patterns.

Runtime Compatibility

This skill is shared by OpenCode, Codex, and Claude Code. Keep instructions tool-agnostic: prefer repository-local scripts, platform developer tools, CLI commands, simulator evidence, screenshots, and explicit manual checks over host-specific features. When a tool is unavailable, record the missing evidence and use the closest deterministic check instead of pretending the platform was verified.

Routing

• Use product-rd-workflow first when the work spans product intent, design, service contracts, implementation, test, review, release, and follow-up.
• Use product-ui-ux-design before or alongside coding for visible page structure, interaction model, density, empty/error/loading states, trust copy, accessibility, and launch acceptance.
• Use ../product-ui-ux-design/references/multi-stack-strategy.md and ../product-ui-ux-design/references/multi-project-token-consistency.md when the mini-program is one of several client stacks under one brand (web desktop + H5 + native app + mini-program). Cross-end brand alignment (color tokens, typography, voice/tone, terminology, navigation labels, trust copy) is owned there, not here. This skill enforces the host-platform constraints on top of those tokens. For the scope of what must align across web + app + mini-program (beyond just theme and logo — including auth/onboarding copy, error vocabulary, payment confirmations, privacy disclosures, share/QR payload schema, deep-link routes), read references/cross-stack-alignment.md.
• Use web-react-dev for the React layer when Taro shares code with a React web project (see Sibling Boundary below).
• Use backend architecture/dev skills for API contracts, auth services, payment callbacks, subscriptions, persistence, async jobs, and admin/ops surfaces.
• For backend HTTP integrations, preserve current client wire behavior unless an explicit consumer-migration decision exists. Classify JSON vs protobuf-backed HTTP using ../platform-service-connectivity/references/protobuf-http-contract-signals.md.
  • First decide whether the client diff touches the HTTP contract or wire behavior. Wire-unchanged page/component/state work does not need a backend owner round-trip and must not claim backend contract conformance.
  • For unrelated client work, classify the diff with the canonical gate. If the surface is out of scope, client work may continue without claiming backend contract conformance.
  • If the canonical gate classifies the diff as in scope, confirm the backend's recorded wire format or route back to the backend contract owner.
  • Routine JSON/OpenAPI changes use the existing API contract record and do not require backend wire-format confirmation when the canonical reference classifies the surface as out of the protobuf wire-format gate.
  • Mini-program request wrappers must consume the backend contract's recorded response envelope per ../platform-service-connectivity/references/http-response-envelope-contract.md: for surfaces on the canonical code/message/data envelope, page/component state reads typed business data from ; other shipped or non-JSON envelopes are consumed per their recorded contract. Read only fields present in the recorded contract — do not infer business fields from unrecorded top-level or fallback shapes — and scatter no duplicate envelope parsing across the client.

Lifecycle and Neighboring Skills

How this skill sits inside the broader delivery loop for a mini-program feature. Each stage names its owning skill and what this skill receives from / hands off to it.

Stage	Owner	What flows into this skill	What this skill hands back
Risk classification	feature-risk-router	Risk tags (money / identity / privacy / write finality / generated content / host capability), required gates	Confirmation that the gate set covers mini-program-specific risks (review policy, host capability, finality across host pay)
Product / cross-stage delivery	product-rd-workflow	Product intent, scope, service contract, release plan	Mini-program-specific delivery considerations (multi-target shipping set, host review timeline, gray release lever choice)
Design (visual, interaction, copy, states)	product-ui-ux-design	Design source (Figma), tokens, state enumeration, copy / voice, accessibility criteria; cross-stack alignment is owned in ../product-ui-ux-design/references/multi-stack-strategy.md + ../product-ui-ux-design/references/multi-project-token-consistency.md	Mini-program platform constraints on top of the design (safe-area, host gesture, capability denial states, host-native affordance), screenshot acceptance per shipped host
Implementation — React layer + pure shared	web-react-dev	Component decomposition, hooks, state ownership, effect discipline, pure shared DTOs / validators / mapping	Mini-program contract on co-owned runtime adapters (auth epoch tuple, request cancellation, storage manifest, finality / idempotency, kill-switch, trace propagation) — enforced via the named co-owned-adapter owner + miniapp-contract tests (see "Sibling Boundary With web-react-dev" → shared-runtime-adapter row for the full gate)
Implementation — mini-program runtime	This skill	Taro lifecycle, host APIs, platform branching, subpackage, capability adapters, multi-target build, review-safe copy	—
Implementation — backend services	Go / Python service skills + llm-inference-integration	API contracts, server idempotency by (principal, tenant, action, business-key, fingerprint), payment reconciliation, share-token issuance, signed capability grants, server-side feature flags	This skill consumes those contracts. If the backend cannot supply a contract that a specific mini-program flow needs (server-business-key idempotency / bounded reconciliation / signed grants / fail-closed flag), route the decision through + with backend owner evidence — the legitimate exits are remove the risky capability, ship a read-only or non-finality subset, record a deferred-gate row with a tracking ticket, or block. Do not strand the work without an owner.

Treat the loop as: risk-route → product/design → develop (this skill + web/backend) → test → release → debug → extract back. Skipping the extract-back step is how a team accumulates implementation hours without the skill ever maturing.

Repo-local agent contracts (AGENTS.md at the repo root and in source directories) are part of the delivery contract: when a change moves a stable boundary, generated surface, workflow, or directory-local rule, update the nearest contract in the same MR and keep coverage in sync per product-rd-workflow's spec / repo-contract sync gate.

When checking a mini-program project against team standards, split conformance into deterministic and agent review evidence. Deterministic checks cover project config, target/platform build commands, subpackage config, generated API/IDL client usage, environment/lane config, TC traceability, CI gates, and required request/trace identifiers in central request wrappers. Agent review checks cover page/component boundaries, host capability contracts, shared adapter safety, finite-value mapping, multi-target release risk, and whether tests/device evidence cover the shipped targets. For the deterministic executor list and the mini-program ESLint config enforcing the two host-boundary invariants (the react-dom/DOM-global ban and TARO_ENV adapter-layer confinement — ESLint config, not a regex source-scan), see testing-strategy/references/fitness-functions.md §4.1.3 (spec 006).

Sibling Boundary With web-react-dev

Taro is React syntax compiled to mini-program runtime; a Taro project typically shares a substantial portion of code with a React web project in the same monorepo. Without an explicit boundary, ownership of state hooks, API clients, and shared components drifts.

Layer	Owner	Notes
React component structure, hooks, JSX, TSX types	web-react-dev	Component decomposition, state lifting, effect discipline are the same rules.
Pure shared layer (DTOs, types, validators, pure mapping)	web-react-dev (monorepo pkg-shared)	No platform branches; no I/O.
Shared runtime adapters consumed by mini-program targets (request client, auth state machine, storage namespace, finality/idempotency wrapper, observability transport)	Co-owned with a named final-decision owner (one engineer per adapter, recorded in repo). web-react-dev sets browser semantics; this skill's contract — full session-epoch tuple fencing, request cancellation across route switch, storage namespacing + manifest + historical-prefix purge, sensitive-field handling, late-callback fencing, server-business-key idempotency, pending-reconciliation with bounded timeout on cold start / page-show / re-login, support-id propagation, kill-switch dimensions, trace propagation — is a blocking acceptance gate before mini-program targets import the adapter. Web may not merge an adapter change that is browser-safe but mini-program-unsafe; the gate's miniapp-contract tests must pass first — the merge record must carry the fixed token gate: miniapp-product-dev SKILL.md Sibling Boundary → shared runtime adapters row plus a passing miniapp-contract run recorded on the change under merge.
Shared design tokens / theme	product-ui-ux-design + per-stack injection	Tokens flow from the design source; injection mechanics per multi-project-token-consistency.md.
Component library choice (Taroify, NutUI-Taro, tdesign-miniprogram)	Co-owned with product-ui-ux-design: design owns UX / token / accessibility / brand-fit criteria; this skill owns runtime fit (package size, host-platform compatibility, framework version compatibility, build pipeline integration). Both signoffs required. See references/framework-choice.md → "What this skill does NOT decide" and ../product-ui-ux-design/references/multi-stack-strategy.md for the design source of truth check.
Taro lifecycle (useReady, useLoad, useDidShow, useDidHide)	This skill	Page lifecycle differs from React DOM lifecycle.

Cross-checking rule: when editing code shared with a React web project, also check the relevant React rule in web-react-dev (state ownership, effects, accessibility, observability). When the code is mini-program-only (config, host API, platform branch), this skill is authoritative.

Core Workflow

Before editing Taro/native mini-program code, page config, host capability adapters, platform project files, styles, assets, or tests, complete enough analysis and planning for the change to be reviewable. Scale the plan to risk: a simple low-risk single-page change can use a short inline plan; multi-target, API-visible, host-capability, platform-review/release, bug-fix, branch/MR, unclear-risk, or high-risk work needs explicit task split, host/target verification matrix, acceptance checks, verification commands, rollback or stop conditions, and named handoffs to testing, web/app, backend, release, or diagnosis skills before edits. Runtime-visible work consumes the canonical Design brief and Test Phase 0 before implementation.

1. Resolve the miniapp platform and delivery shape.

   • Host platform target(s): WeChat, Alipay, Douyin/TikTok, Baidu, or several at once. Multi-target = a separate verification matrix; one target compiling is not proof another target passes.
   • Framework: confirm Taro as the project's framework (default for this skill). If the repo is native, uni-app, Remax, kbone, or mpvue, apply this skill's recipes with framework-equivalent substitutions and call out the substitution in the change description.
   • For Taro: confirm Taro major version, React version, build target list (taro build --type weapp/alipay/tt/swan/h5/rn), and which targets are actually shipped vs. listed-but-unverified.
   • Target: new page, tab, component, package/subpackage, plugin, webview bridge, or platform capability.
   • Release channel: developer tools preview, experience build, gray release, full release, or platform review submission.

2. Analyze the existing client surface before editing.

   • Locate page ownership, route registration, tab/subpackage config, app/global state, API client, storage wrapper, auth/session owner, analytics wrapper, and tests.
   • For Taro: locate app.config.ts / app.config.js (route + tab + subpackage + permission registration), per-page *.config.ts, config/index.ts (build config), project.config.json / project.private.config.json (WeChat target), project.alipay.json (Alipay target), project.tt.json (Douyin target) and similar per-target project config files, and the Taro plugin pipeline. mini.project.json is the native-Alipay project config, not the Taro Alipay project config.
   • For native miniapp: WeChat uses app.json + project.config.json + sitemap.json + ext.json (plugin/extension); Alipay uses app.json + mini.project.json; Douyin/Baidu use their own platform project files. manifest.json + pages.json is uni-app shape, not native; only include it when the repo is uni-app. Also inspect package config, build scripts, and CI jobs as applicable.
   • Identify platform-branching code paths: process.env.TARO_ENV checks in Taro, conditional compilation blocks, or platform-specific files (*.weapp.tsx, *.alipay.tsx). Confirm branching lives at the adapter/wrapper layer, not in render code.

Non-Negotiable Rules

• Do not treat a browser or H5-only preview as proof that a miniapp platform passes. For Taro, taro build --type h5 passing is not evidence that weapp/alipay/tt/swan targets pass.
• Do not push large or high-frequency setData payloads across the logic↔render bridge. setData serializes its payload from the logic thread to the render thread on every call, so a multi-hundred-KB payload or a per-scroll-tick / per-keystroke call janks rendering, and the host drops an oversized call (WeChat documents a per-setData size limit on the order of 1 MB — confirm the exact current value in the platform docs). Send only the changed fields via data-path keys (e.g. this.setData({'list[3].done': true})), not the whole list; throttle/debounce high-frequency updates; and page or virtualize long lists rather than re-pushing the full array. (WeChat 小程序平台性能优化指南：setData 数据量与调用频率，以当前官方文档为准；Taro setState compiles to setData, so the same limit applies.)
• Do not call multi-platform miniapp work complete because one host platform compiled.
• Do not add direct platform API calls when the repo has wrappers or adapters.
• Do not import react-dom or use real browser-only APIs (DOM mutation, browser observers, RAF/layout APIs, browser globals) in Taro code that compiles to a mini-program target; isolate that code behind the H5 build target.
• Do not sprinkle process.env.TARO_ENV branches inside render code as a project convention; confine platform branching to adapter/wrapper modules or platform-specific files. (Taro permits inline branching; the guardrail is a maintainability rule, not a framework limitation.)
• Do not use Taro.eventCenter as the canonical owner of durable cross-page state; reserve it for navigation handoff and simple lifecycle events, and clean up listeners on useDidHide / useUnload.
• Do not ship a page without verifying route registration, entry scene/share params, tab vs. navigateTo vs. switchTab vs. redirectTo vs. reLaunch semantics, and page-stack depth budget. Routing defects are a leading cause of host-platform review rejection.
• Do not leave async work running across page hide/unload or route switch: every long-running operation lives under a per-page controller with cancel + lifecycle epoch + late-callback ignore. Callbacks arriving after the epoch advances are dropped.

Reference Loading

• For source provenance, current extraction boundary, and keep/merge/discard decisions, read references/source-evidence-map.md when auditing or re-extracting this skill.
• For platform-specific capability and config checks, read references/platform-capabilities.md.
• For product/page acceptance and UI state checklist, read references/product-page-checklist.md.
• For API, auth, storage, analytics, and high-risk finality contracts, read references/contracts-and-state.md.
• For QA, developer-tool, real-device, review submission, release, and rollback checks, read references/qa-release.md.
• For framework choice (Taro vs native vs uni-app vs Remax/kbone vs per-platform split) and decision factors, read references/framework-choice.md.
• For cross-stack alignment scope (what must align across web + app + mini-program beyond theme/logo — auth copy, error vocabulary, payment confirmation, privacy disclosure, share payload schema, deep-link routes), read references/cross-stack-alignment.md.
• For incorporating online best practices (canonical Taro / WeChat / Alipay / Douyin examples, top-tier mini-programs as UX idiom library, vetting weak vs strong online sources) without overclaiming what observation can prove, read references/online-practice-uptake.md.
• For cross-stack brand alignment (web desktop + H5 + native app + mini-program sharing one brand), read ../product-ui-ux-design/references/multi-stack-strategy.md and ../product-ui-ux-design/references/multi-project-token-consistency.md.