spatial-app-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

Use this skill for architecture questions, not API questions.

Use it when:

you need to choose the right surface: window, volume, immersive space, or a mixed flow
you are deciding which state is app-wide, scene-scoped, immersive-scoped, or view-local
a root file owns too many concerns and needs a refactor plan
you need a file or module plan before writing or splitting SwiftUI code

使用此技能解决架构相关问题，而非API问题。

适用于以下场景：

Reference	When to Use
`references/surface-selection.md`	When choosing window vs volume vs immersive space and their lifecycle boundaries.
`references/state-ownership.md`	When deciding what belongs to the app, scene, feature coordinator, RealityKit owner, or view.
`references/file-layouts.md`	When proposing a layered or feature-sliced file and module shape.
`references/refactor-playbook.md`	When the app already exists and the main task is refactoring without breaking behavior.
`references/anti-patterns.md`	When you need to call out structural smells or explain why an approach is wrong.

参考资料	使用场景
`references/surface-selection.md`	当需要选择窗口、体积空间或沉浸式空间及其生命周期边界时。
`references/state-ownership.md`	当需要确定哪些内容属于应用、场景、功能协调器、RealityKit所有者或视图时。
`references/file-layouts.md`	当需要提出分层或按功能划分的文件与模块结构时。
`references/refactor-playbook.md`	当应用已存在，主要任务是在不破坏现有功能的前提下进行重构时。
`references/anti-patterns.md`	当需要指出结构缺陷或解释某种方案为何不可行时。

Classify the feature by user job and current or intended surface.
Choose the owning surface model: window, volume, immersive space, or a combination.
Assign state ownership boundaries: app, scene, immersive, feature, view.
Choose a file/module shape that matches the ownership model.
Define the implementation handoff: SwiftUI, RealityKit, ARKit, SharePlay, or build/debug.
If this is a refactor, sequence the extraction so behavior stays stable.
Verify the structure with
```
build-run-debug
```
after the first usable slice.

Switch to
```
spatial-swiftui-developer
```
when the surface and ownership model are already chosen and the next step is implementing SwiftUI APIs.
Switch to
```
realitykit-visionos-developer
```
when the work is mainly about entities, components, systems, or RealityKit runtime behavior.
Switch to
```
arkit-visionos-developer
```
when the architecture choice depends on provider constraints, anchors, or tracked-world behavior.
Switch to
```
shareplay-developer
```
when the app structure is driven by group activity or shared immersive presence.
Switch to
```
build-run-debug
```
after the first usable architectural slice exists and needs validation.

Do not choose immersion by novelty alone.
Do not let transient views own long-lived immersive lifecycle or RealityKit mutation.
Preserve strong repo conventions when they are already coherent.

Provide:

the next implementation handoff:

spatial-swiftui-developer

realitykit-visionos-developer

arkit-visionos-developer

shareplay-developer

, or

build-run-debug

需提供：

下一步的实现交接方向：

spatial-swiftui-developer

、

realitykit-visionos-developer

、

arkit-visionos-developer

、

shareplay-developer

或

build-run-debug