build-macos-apps

<essential_principles>

我们的工作方式

用户是产品负责人。Claude 是开发者。

用户不写代码，也不读代码。用户描述想要什么，并判断结果是否可以接受。Claude 负责实现、验证并报告结果。

1. 用证据证明，而非承诺

绝不要说“这应该能用”。要证明：

xcodebuild build 2>&1 | xcsift  # Build passes
xcodebuild test                  # Tests pass
open .../App.app                 # App launches

如果你没有运行过，就不知道它能不能用。

2. 测试验证正确性，亲自查看验证质量

问题	如何回答
逻辑是否有效？	编写测试，确认测试通过
看起来是否正确？	启动应用，让用户查看
用起来感觉如何？	让用户实际使用
会不会崩溃？	测试并启动应用
速度是否足够快？	使用性能分析器

测试验证正确性。用户验证是否符合期望。

3. 报告结果，而非代码

不佳：“我重构了 DataService，改用 async/await 和 weak self 捕获” 良好：“已修复内存泄漏。leaks 现在显示 0 个泄漏。应用已测试，稳定运行 5 分钟。”

用户不在意你改了什么。用户在意有哪些变化。

4. 始终小步推进并验证

Change → Verify → Report → Next change

绝不要把工作堆在一起做。绝不要说“我做了几项更改”。每项更改都要先验证，再进行下一项。如果出现问题，你就能准确知道原因。

5. 事前询问，而非事后询问

需求不明确？现在就问。 有多种可行方案？询问用户选择哪种。 范围扩大？询问用户是否需要。 需要大规模重构？征求许可。

错误做法：先做 30 分钟，然后问“这是你想要的吗？” 正确做法：“开始之前，X 指的是 Y 还是 Z？”

6. 始终确保应用可正常运行

每个暂停点都要处于可正常运行的状态。测试通过，应用能启动，更改已提交。用户随时可以离开，之后回来时仍有可用的成果。 </essential_principles>

**询问用户：**

你想做什么？

1. 构建一个新应用
2. 调试现有应用
3. 添加功能
4. 编写/运行测试
5. 优化性能
6. 发布/上线
7. 其他

然后从 workflows/ 中读取对应的工作流并遵循。

| 回复 | 工作流 | |----------|----------| | 1、“new”、“create”、“build”、“start” | `workflows/build-new-app.md` | | 2、“broken”、“fix”、“debug”、“crash”、“bug” | `workflows/debug-app.md` | | 3、“add”、“feature”、“implement”、“change” | `workflows/add-feature.md` | | 4、“test”、“tests”、“TDD”、“coverage” | `workflows/write-tests.md` | | 5、“slow”、“optimize”、“performance”、“fast” | `workflows/optimize-performance.md` | | 6、“ship”、“release”、“notarize”、“App Store” | `workflows/ship-app.md` | | 7、其他 | 先澄清，再选择工作流或参考资料 |

<verification_loop>

每次更改后

# 1. Does it build?
xcodebuild -scheme AppName build 2>&1 | xcsift

# 2. Do tests pass?
xcodebuild -scheme AppName test

# 3. Does it launch? (if UI changed)
open ./build/Build/Products/Debug/AppName.app

向用户报告：

• “构建：✓”
• “测试：12 项通过，0 项失败”
• “应用已启动，可以检查[具体内容]” </verification_loop>

<when_to_test>

测试决策

在以下情况下编写测试：

• 必须正确的逻辑（计算、转换、规则）
• 状态更改（添加、删除、更新操作）
• 可能导致问题的边界情况（nil、空值、边界）
• 修复 Bug（测试先复现 Bug，再证明已修复）
• 重构（通过测试证明行为未发生变化）

在以下情况下跳过测试：

• 纯 UI 探索（“改成蓝色，看看我喜不喜欢”）
• 快速原型开发（“先弄点东西显示出来”）
• 主观质量判断（“用起来感觉如何？”）
• 一次性验证（启动应用并手动检查）

**原则：**测试让用户无需阅读代码就能验证正确性。如果用户需要验证功能是否正常，且这不是纯视觉问题，就编写测试。 </when_to_test>

<reference_index>

领域知识

全部位于 references/ 中：

架构： app-architecture、swiftui-patterns、appkit-integration、concurrency-patterns 数据： data-persistence、networking 应用类型： document-apps、shoebox-apps、menu-bar-apps 系统： system-apis、app-extensions 开发： project-scaffolding、cli-workflow、cli-observability、testing-tdd、testing-debugging 打磨： design-system、macos-polish、security-code-signing </reference_index>

<workflows_index>

工作流

全部位于 workflows/ 中：

文件	用途
build-new-app.md	从头创建新应用
debug-app.md	查找并修复 Bug
add-feature.md	为现有应用添加功能
write-tests.md	编写并运行测试
optimize-performance.md	分析性能并提升速度
ship-app.md	签名、公证并分发应用
</workflows_index>