第二步：零代码起步——用Claude Code生成SwiftUI骨架与命理数据模型

准备工作：环境与工具配置

在正式进入命理应用开发前，必须搭建一个稳定、可预测、与 Claude Code 高度协同的开发环境。这不是简单的“装好 Xcode 就行”，而是为 AI 编程建立清晰的边界和契约——让 Claude 知道它在什么系统上运行、用什么语法、遵循什么约束。

首先，确认你的 macOS 版本 ≥ Ventura（13.0），并在终端执行以下命令验证 Xcode 命令行工具完整性：

xcode-select --install  # 若提示已安装，则跳过；否则按向导完成安装
sw_vers && xcodebuild -version

✅ 正确输出应类似：

ProductName:    macOS  
ProductVersion: 14.5  
BuildVersion:   23F79  
Xcode 15.4  
Build version 15F31d

接着，下载并安装 Cursor IDE（v0.48+ 推荐）。它对 Claude Code 的集成最成熟：打开设置 → Settings → Extensions → 搜索 “Claude Code” → 启用插件。API Key 配置入口位于：
Settings → Extensions → Claude Code → API Key（⚠️ 不是 Cursor 自带的 “Claude” 插件，务必认准官方图标）
Cursor 中 Claude Code 插件配置界面

创建项目：启动 Cursor → File → New Project → App → 选择模板：

Interface: SwiftUI
Life Cycle: Swift UI App
Language: Swift
Organization Identifier: 如 com.yourname.bazi

创建后，立即打开 PreviewProvider 所在文件（通常是 ContentView.swift 或 AppNameApp.swift），点击右上角 ▶️ 预览按钮。若看到 “Hello, world!” 且无编译错误，说明 SwiftUI 基础环境就绪。

📌 关键注意事项（极易踩坑！）：

禁用 Xcode 自动格式化：Xcode → Settings → Text Editing → Formatting → ☐ Automatically format code on paste（取消勾选）；同时关闭 Organize Imports 和 Wrap Lines。否则 Claude 生成的缩进/换行将被 Xcode 强制重写，导致预览崩溃。
检查 Swift Concurrency 警告：在 Project Settings → Build Settings → Swift Compiler - Warnings 中，确保 Strict Concurrency Checking 设为 Targeted（非 Complete），且 Suppress Warnings 为 ❌ 关闭状态——Claude 生成的异步代码需显式标注 @MainActor 或 Task { }，不能靠压制警告蒙混过关。

第一步：用自然语言定义命理数据需求（Claude 的输入指令设计）

AI 不读心，只读 Prompt。一句模糊的“做个八字App”会让 Claude 输出 10 个不兼容的模型草稿；而精准的领域指令，能直接生成可落地的 Swift 结构体。

我们以核心数据模型为例，给出一个高精度 Prompt 拆解模板：

“请为中华传统八字命理应用生成 Swift 数据模型，严格遵循以下要求：
① 根对象名为 BaZiChart，包含四柱属性：yearStemBranch, monthStemBranch, dayStemBranch, hourStemBranch（类型均为 StemBranch）；
② 十神关系定义为枚举 TenGod，原始值（rawValue）为 String，必须包含：.rightOfficial("正官"), .sideWealth("偏财"), .rightSeal("正印"), .harmfulResource("七杀"), .robWealth("劫财")；
③ 大运起运时间用结构体 MajorPeriodStart，含 ageInYears: Int（实岁）和 isLunarAge: Bool（虚岁开关）；
④ 所有模型必须：a) 实现 Codable；b) 使用 Swift 5.9 语法；c) 属性名 camelCase（如 heavenlyStem），枚举名 PascalCase（如 HeavenlyStem）；d) 每个类型顶部添加 /// 文档注释，说明业务含义（如 /// 日主，即日柱天干，决定命局五行旺衰核心）；e) JSON 键名使用 snake_case（如 "heavenly_stem" → 映射到 heavenlyStem）”

✅ 有效技巧总结：

✅ 强制版本：Swift 5.9 避免生成 async let 等旧版不兼容语法；
✅ 命名锁死：camelCase/PascalCase 消除大小写歧义；
✅ 注释驱动：/// 注释不仅是文档，更是 Claude 理解业务语义的锚点。

❌ 典型错误对照：

错误 Prompt	问题	修正后
“加点命理功能”	无实体、无边界	“添加 `func wuXingCompatibility(_ other: StemBranch) -> CompatibilityLevel` 方法，返回 `.harmony`/`.conflict`/`.neutral`”
“日主字段叫‘日主’”	中英混杂，Swift 不允许中文标识符	“属性名 `dayMaster: HeavenlyStem`，文档注释：`/// 日主，即日柱天干...`”

第二步：生成 SwiftUI 视图骨架——从首页到详情页的声明式构建

视图层是用户感知的入口。我们不追求一次性生成完整 UI，而是分层、可组合、预览优先地生成骨架。

生成 `HomeView.swift`

Prompt 示例：

“生成 SwiftUI 列表页 HomeView，使用 List + NavigationStack：① 顶部搜索栏（TextField 绑定 @State private var searchText: String）；② 列表显示 @StateObject private var dataManager: BaZiManager 中的 charts；③ 每行显示 chart.displayName（如‘张三｜甲子丙寅戊辰庚申’）和 chart.lastModified；④ 点击行跳转到 ChartDetailView(chart: $chart)；⑤ 右上角 + 按钮调用 dataManager.createNewChart()；⑥ 提供 PreviewProvider，用 3 条模拟数据初始化 BaZiManager()”

生成后，立即检查三项：

@StateObject var dataManager = BaZiManager() —— Claude 常漏掉 = ... 初始化；
NavigationStack { ... } 是否包裹整个内容（SwiftUI 6+ 必需）；
Preview 中是否注入 .environmentObject(BaZiManager())。

生成 `ChartDetailView.swift`

Prompt 示例：

“生成详情页 ChartDetailView，接收 @Binding var chart: BaZiChart：① 用 VStack 分区：标题、四柱 Grid（2×2）、十神矩阵（5×2 表格）、大运时间轴（ForEach 大运数组）；② 四柱每格显示 stemBranch.heavenlyStem.symbol + stemBranch.earthlyBranch.symbol（如‘甲子’）；③ 十神矩阵首列为十神名（.rightOfficial.rawValue），第二列为对应关系描述（如‘克我者，阴阳同性’）；④ 所有文本使用 Font.caption，关键字段加粗；⑤ Preview 提供单个 BaZiChart.sample() 数据”

HomeView 与 ChartDetailView 布局示意

⚠️ 重要缝合点：Claude 不会自动生成副作用逻辑。你必须手动在 HomeView.onAppear { dataManager.loadFromDisk() } 和 ChartDetailView.onAppear { chart.validate() } 中补全数据加载与校验。

第三步：构建强类型命理数据模型——从 JSON Schema 到 Swift Codable

这是整个应用的数据基石。我们让 Claude 直接将命理规则翻译为 Swift 类型系统。

核心模型 Prompt 要点：

“生成以下 Codable 结构体，全部支持 JSONEncoder/Decoder：
StemBranch: 含 heavenlyStem: HeavenlyStem, earthlyBranch: EarthlyBranch, id: UUID；
HeavenlyStem: 枚举，rawValue String，值为 .jia("甲"), .yi("乙"), ...；
EarthlyBranch: 枚举，rawValue String，值为 .zi("子"), .chou("丑"), ...；
WuXing: 枚举 .wood, .fire, .earth, .metal, .water；
StemBranch.wuXing: 计算属性，根据天干地支查表返回五行（例：天干‘甲’→木，地支‘子’→水，最终取‘水’）；
JSON 键名严格 snake_case：heavenly_stem, earthly_branch；
所有嵌套模型必须实现 Codable，且 CodingKeys 显式声明。”

关键代码示例（Claude 生成后需人工校验）：

/// 八字四柱中的单柱，如年柱、月柱  
struct StemBranch: Codable, Identifiable {  
    let id = UUID()  
    let heavenlyStem: HeavenlyStem  
    let earthlyBranch: EarthlyBranch  
    
    /// 五行属性（由天干地支自动推导，非用户输入）  
    var wuXing: WuXing {
        // Claude 会按《滴天髓》规则生成此逻辑
        switch (heavenlyStem, earthlyBranch) {
        case (.jia, .zi): return .water // 甲木坐子水，水生木，取水
        case (.bing, .yin): return .fire  // 丙火坐寅木，木生火，取火
        default: return .water
        }
    }
    
    enum CodingKeys: String, CodingKey {
        case heavenlyStem = "heavenly_stem"
        case earthlyBranch = "earthly_branch"
    }
}

❌ 动态键陷阱：若 JSON 含 "2025": { "luckyElement": "fire" } 这类年份键，Claude 可能错误生成 var _2025: AnnualForecast。正确做法：

struct AnnualForecast: Codable { /* ... */ }
struct BaZiChart: Codable {
    let annualForecasts: [String: AnnualForecast] // ✅ 动态键必须用字典
}

第四步：集成与调试——让 Claude 生成的代码真正跑起来

生成 ≠ 运行。这一步聚焦缝合、修复、验证。

编译修复清单（逐行检查）：

补全缺失 import：import Foundation（Codable）、import SwiftUI（视图）、import UniformTypeIdentifiers（文件操作）；
修正 @StateObject 初始化：@StateObject var manager = BaZiManager()（Claude 常写成 @StateObject var manager: BaZiManager）；
Preview 数据升级：将 MockData() 替换为 BaZiChart.sample()，确保真实数据流。

运行时验证：

在 ContentView.swift 中注入测试实例：

struct ContentView: View {
    @StateObject var chart = BaZiChart.sample()
    var body: some View {
        ChartDetailView(chart: $chart)
            .previewDevice("iPhone 15")
    }
}

检查布局：拖动预览器尺寸，确认 Grid 和 ScrollView 响应正常；
测试深色模式：View.previewLayout(.sizeThatFits).colorScheme(.dark)。

⚠️ 沙盒与并发两大雷区：

❌ 错误：Bundle.main.url(forResource: "data", type: "json") → 沙盒中 main Bundle 不含资源；
✅ 正确：Bundle.module.url(forResource: "data", type: "json")（Cursor 项目默认启用 Swift Package）；
❌ 错误：func load() async { ... } 被直接调用 → SwiftUI 6+ 报错 MainActor 违规；
✅ 正确：在 onAppear 中用 Task { await manager.load() } 包裹。

常见问题（FAQ）与进阶技巧

Q1：“Preview 报错 ‘Type ‘some View’ cannot conform to ‘View’’？”

→ 根因：Claude 有时省略 return 或未用 Group { } 包裹多子视图。
✅ 解决：检查 body 内是否所有分支都有 return；多子视图外加 Group { ... } 或 VStack { ... }。

Q2：“十神枚举生成 `.zhengYin` 而非 `.rightSeal`？”

→ 根因：Prompt 未强制英文语义命名。
✅ 解决：在 Prompt 开头加一句：“所有枚举值必须使用英文语义命名：正官→.rightOfficial，偏财→.sideWealth，正印→.rightSeal”

进阶技巧（提升生产力）：

主题优化：对已生成的 ChartDetailView.swift，追加 Prompt：
“Refine this view to support dark mode: replace all hardcoded colors (e.g., Color.blue) with dynamic alternatives using Color(UIColor.systemBlue) or Color.primary；add .preferredColorScheme(.unspecified) to PreviewProvider.”
校验增强：粘贴 BaZiChart.swift 全文，追加：
“为 BaZiChart 添加 func validate() -> [ValidationError] 方法，校验：① dayStemBranch.heavenlyStem != nil；② majorPeriodStart.ageInYears 在 0–5 范围内；③ 返回 [ValidationError(field: "dayStemBranch", message: "日柱天干不可为空")] 格式数组。”

命理App最终预览效果：深色模式下的四柱与十神矩阵

至此，你已掌握用 Claude Code 驱动专业级 SwiftUI 命理应用的完整链路：从环境筑基、Prompt 设计、视图分层、模型强类型，到缝合调试。记住——Claude 是超级助手，不是替代者；你才是架构师、校验员与最终决策者。 下一篇，我们将用相同方法接入 Core Data 与 iCloud 同步，让八字数据真正「活」在用户设备间。

准备工作：环境与工具配置#

第一步：用自然语言定义命理数据需求（Claude 的输入指令设计）#

第二步：生成 SwiftUI 视图骨架——从首页到详情页的声明式构建#

生成 HomeView.swift#

生成 ChartDetailView.swift#

第三步：构建强类型命理数据模型——从 JSON Schema 到 Swift Codable#

第四步：集成与调试——让 Claude 生成的代码真正跑起来#

编译修复清单（逐行检查）：#

运行时验证：#

常见问题（FAQ）与进阶技巧#

Q1：“Preview 报错 ‘Type ‘some View’ cannot conform to ‘View’’？”#

Q2：“十神枚举生成 .zhengYin 而非 .rightSeal？”#

进阶技巧（提升生产力）：#