macos-apps

工作方式

用户是产品负责人。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. 始终保持可用状态

每个停下来的节点都必须处于可用状态。测试通过、应用可启动、更改已提交。用户可以随时离开，之后回来时仍能使用正常工作的成果。

需求收集

询问用户：

你想做什么？

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、其他	先澄清，再选择工作流或参考资料

每次更改后

# 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 项失败”
• “应用已启动，可以检查[具体内容]”

测试决策

在以下情况下编写测试：

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

在以下情况下跳过测试：

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

**原则：**测试让用户无需阅读代码即可验证正确性。如果用户需要确认它能否正常工作，而且这不是纯视觉效果，就编写测试。

领域知识

均位于 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

常见陷阱与调试： common-pitfalls

常见陷阱

macOS 应用开发中有一些容易踩的坑，会阻碍应用发布。你可能会遇到以下失败情况：

高严重性问题

• 沙盒违规 — 缺少授权（钥匙串、文件访问、网络）会导致静默失败或被 App Store 拒绝
• 代码签名失败 — 配置描述文件过期、捆绑包标识符不匹配、钥匙串中缺少证书
• App Store 拒绝 — 使用私有 API、元数据不完整、缺少隐私政策
• SwiftUI 状态错误 — @Model 对象未使用 @Bindable、可变类视图无法更新、NavigationStack 无法导航
• macOS 版本不兼容 — 使用目标 macOS 版本中不存在的 API、弃用的 API、遗漏可用性检查

应对方法

发布前： 阅读 common-pitfalls.md。其中记录了每种失败情况，包括：

• 你会看到的确切错误消息或症状
• 问题发生的原因
• 代码修复或配置变更
• 如何验证问题已修复

出现问题时： 在 common-pitfalls.md 中搜索错误消息。大多数问题都已列出。

这些参考文件之所以存在，是因为这些问题可以预见，也可以避免。请加以利用。

工作流

全部位于 workflows/ 中：

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