In this post

1. 项目起始阶段：公理设计方法分解功能

在项目之初，独立开发者应充分收集和梳理光学研发应用的需求，将用户的整体目标分解为明确的功能需求（FR，Functional Requirements）。接着运用 公理设计 理论，将每一项 FR 映射为相应的设计参数（DP，Design Parameter），形成 FR-DP 映射表 和初步的模块划分。公理设计强调功能独立性公理（每个 FR 应独立实现）和信息最少公理（设计应尽量简单）。具体而言：

  • FR-DP 一一对应：理想情况下，功能需求的数量等于设计参数的数量，每个 FR 只关联一个 DP。这样设计矩阵呈对角阵形式，意味着各模块尽可能独立，修改某一需求只影响对应模块，实现低耦合、高内聚。
  • 建立模块图：根据 FR-DP 映射结果绘制模块依赖图或层次结构图。顶层 FR 对应主要模块，下设子 FR 进一步分解为子模块。确保模块之间尽量松耦合（正交），避免一个模块承担多个无关需求。
  • 示例：假设需求包含“光路建模”和“实验设备控制”两个 FR，则可设计对应的“光学建模模块”（DP1）和“设备控制模块”（DP2）。两者独立实现各自功能，只有必要的接口交互。这种划分遵循公理设计的独立性，避免一个模块承担多重功能导致互相影响。

完成 FR-DP 映射表和模块图后，相当于制定了项目的架构蓝图。开发者在这一阶段产出明确的功能列表、模块职责说明以及它们之间的接口关系，为后续开发提供清晰指引。

2. 需求转化为行为：BDD 与 Gherkin 场景

确定功能规格后，将需求转化为可测试的行为描述，这里建议采用行为驱动开发（BDD） 方法。使用 Gherkin 语言编写用户故事和场景，使业务/科研需求以“Given-When-Then”的形式呈现：

  • 撰写特性文件：为每个功能或模块创建一个特性（Feature），包含若干场景（Scenario） 描述应用在不同情境下的行为。Gherkin 是接近自然语言的领域特定语言，采用简单关键词（如 Given、When、Then）描述前提、动作和期望结果。例如：

    Feature: 光束聚焦计算
    Scenario: 计算透镜焦点位置
    Given 已知入射光束参数和透镜曲率
    When 调用焦点计算功能
    Then 返回的焦距结果应与理论值相符

  • 业务人员可读：Gherkin 描述的场景不涉及代码实现细节，业务或科研人员也能读懂，从而参与校验需求是否正确表达。这确保需求理解的一致性。

  • 转换为测试：编写这些场景后，可借助 Python 的 BDD 框架（如 pytest-bdd 或 behave）将 Gherkin 场景与实际测试代码绑定。每个 Given/When/Then 步骤都对应一个 Python 函数实现。当场景运行时，将调用这些函数以验证行为是否满足预期。

通过 BDD，需求被逐步细化为具体的验收测试 场景。开发者与 AI 在阅读同一套行为描述，使 AI 更加明确代码需实现的业务逻辑和验证标准。

3. TDD 与 AI 结合：测试驱动代码生成

在进入编码阶段，采用测试驱动开发（TDD） 策略与 AI 配合，让测试用例来驱动代码编写：

  • 先写测试用例：根据前述 BDD 场景或模块规格，先用 pytest 编写细粒度的单元测试和集成测试。每个测试关注一个功能点或业务逻辑。例如为光束聚焦计算编写测试函数，断言给定参数下输出的焦距是否正确。
  • AI 生成实现：在测试用例编写完成后，利用 AI（如 ChatGPT 编程助手）根据测试要求生成代码。开发者可以将测试代码或其描述提供给 AI，请求“实现通过这些测试的函数/模块代码”。例如使用命令行工具 “AI + TDD”：开发者编写好测试后，由 GPT 模型自动生成使测试通过的代码。AI 通过理解测试用例中的断言和文档来推断所需的功能，实现相应代码逻辑。
  • 运行测试验证：生成的代码需立即运行 pytest 来验证。如果测试全部通过，则基本功能满足需求；如有未通过项，分析失败原因并反馈给 AI 改进代码或由开发者调整测试和需求描述。TDD 短迭代的特点使 AI 生成的代码及时接受检验，确保问题早发现早纠正。
  • 迭代完善：逐个功能点循环上述过程。每次先写新的测试，再借助 AI 生成或改进实现。随着测试集增大，AI 会在编写新功能时受到已有测试失败的约束，提示哪些旧功能可能被影响，从而指导 AI 避免引入回归问题或进行必要的修改。由此测试用例也成为 AI 的“记忆”：在需求分析环节充当规格描述和需求确认的角色；在实现和交付环节则作为验证设计完成与保障软件持续演进质量的安全网。
  • 持续重构：在功能测试通过后，开发者可以要求 AI 重构代码以提高质量（保持测试通过）。例如，让 AI 优化代码结构、消除重复、提高可读性，然后再次运行测试确保重构未引入新错误。TDD 强调测试先行、及时重构，AI 可协助在重构时快速调整代码，确保设计始终简洁、性能合理。

TDD 与 AI 结合能够大幅提升开发效率：开发者聚焦于设计测试、把控需求，而将具体编码工作交给 AI 完成。由于所有功能都有测试验证，通过测试即意味着满足需求规格，从而保障代码正确性和稳定演进。实践表明这种**“测试先行、AI 跟随”的开发方式** 非常有效。需要注意的是，测试用例本身必须全面而准确，开发者应投入足够精力编写高质量的测试，这样 AI 才有明确的目标去实现。

4. 函数式编程在 AI 生成代码中的应用

为提高 AI 生成代码的质量和可测试性，建议在设计和实现时融入函数式编程思想：

  • 数据纯化（Pure Functions）：尽量将业务逻辑编写为纯函数，即相同输入总是产生相同输出，并且不引起任何可观察的系统状态变化（无副作用）。纯函数不依赖全局状态，不修改外部变量。例如，一个计算光强分布的函数仅依赖输入参数，返回计算结果而不打印日志或写文件。纯函数具有可预测性和无副作用的特性，使其行为独立可控。
  • 易于测试和调试：纯函数的确定性大大降低了测试复杂度。测试时只需提供输入，断言输出是否符合预期，无需搭建复杂环境。此外，由于没有隐藏的状态变化，若输出不符期望，问题定位也更直接——源代码中纯函数越多，单元测试就越容易编写。
  • 避免副作用：除纯计算部分外，不可避免的副作用（如文件读写、硬件操作）应与核心逻辑隔离。例如，在光学设备控制软件中，将与设备通讯的 I/O 操作封装在接口层，业务层函数仅返回设备指令数据，由接口层统一发送。这样设计让 AI 生成的业务逻辑部分更纯粹，可独立测试，并在真实运行时通过少量接口代码接入外部环境。
  • 函数组合与复用：鼓励将复杂功能拆解为多个小函数，通过函数组合完成更复杂的任务。这种可组合性使 AI 可以逐个实现小函数，再由开发者或 AI 组合调用完成高阶功能。同时小函数往往更接近纯函数，实现时上下文依赖少，AI 理解起来也更简单，生成错误的概率降低。比如将光线追迹算法拆分为“单步追迹”、“边界反射计算”等函数，各自独立实现并测试，然后组合实现完整算法。
  • 不可变数据：在可能情况下使用不可变的数据结构，避免在 AI 生成代码中出现过多共享可变状态。可考虑使用诸如元组替代列表（需要改变时返回新列表）、减少全局变量等方式来降低状态复杂性，使 AI 产出的代码行为更易推断，不易引入隐含的副作用错误。

通过推广函数式编程原则，开发者实际是在营造一种**“AI 友好”**的代码环境：模块化、无隐含依赖、易检验。这不仅让 AI 更准确地完成代码生成任务，也提高了代码本身的健壮性和可维护性。

5. 提交与版本控制：Git 分支管理与协作

在人机协同开发中，良好的版本控制策略可以确保开发节奏有序、代码质量稳定。针对独立开发者使用 Git 的情况，提出以下建议：

  • 分支管理策略：采用清晰的分支模型，如经典的 Git Flow 模式。

    • 主分支（master/main）：唯一的主分支用于存放稳定发布版本代码。只有在需要发布新版本时才从开发分支合并过来，保持主分支随时可交付。
    • 开发分支（develop）：日常开发在 develop 分支进行，新功能和改动都先集成在此。主分支的发布版本也会及时合并回开发分支，确保开发分支包含最新的稳定代码。
    • 功能分支（feature）：针对每个新功能或重要改动，从 develop 分支拉出独立的功能分支进行开发。功能完成并通过测试后，再合并回 develop，然后删除该功能分支，使代码库的常设分支始终只有 Master 和 Develop。对于紧急修复，可采用类似的 hotfix 分支从 Master 派生修补 bug 后再合并。
    • 分支命名：使用有意义的命名，如 feature-光束优化、fix-内存泄漏 等，使他人（或将来的自己）一目了然分支意图。

  • 提交频率与粒度：勤提交、小步快走。每次提交 (commit) 都应尽可能小且自洽，包含一个独立的修改主题（例如完成一个测试用例所需的实现，或修复一处缺陷）。避免将大量无关修改混在一次提交中。细粒度的提交方便回滚和审查，也让 AI 生成的代码变更更可控。

  • Commit 信息规范：编写清晰规范的提交消息。消息应概括本次改动的内容和原因，必要时可引用相关的需求或问题 ID。遵循一定的格式（例如 Conventional Commits 规范，以 feat:、fix: 前缀标识功能或修复）可以提高团队沟通效率。良好的提交记录有助于理解代码演变并管理变更风险。在人机协作下，提交信息也可标注由 AI 辅助完成的部分以供将来参考（例如在详细描述中注明“此实现由 GPT-4 生成，经人工调优”），但这非必需。

  • 协同工作流程：尽管是独立开发者，仍可使用 Pull Request (PR) 流程来自我审核。即使不经他人审查，开发者也可以通过 PR 界面的 diff 查看和审视 AI 提交的代码差异，确保更改符合预期后再合并。这充当一种质量 Gate。在 PR 讨论区，开发者可以记录对 AI 生成代码的评审意见或给未来的自己提示。

通过以上策略，Git 仓库将保持井井有条，各分支职责分明，提交历史清晰。这对于长期项目尤为重要，能够防止因为 AI 引入大量变更而难以管理版本。另外，借助这些规范，人和 AI 的协同痕迹被很好地记录下来，为后续调试优化提供依据。

6. 持续验证流程：自动化测试与回归

引入 AI 协助编码后，更需要建立持续验证机制来保证代码质量不受影响。建议打造从本地到持续集成的完整测试流水线：

  • 本地频繁测试：开发者应养成频繁运行测试的习惯。在每次 AI 生成或修改代码后，立刻运行 pytest 执行相关测试用例，确保改动未破坏既有功能。可以配置 pytest.ini 或使用标签（markers）以选择运行特定子集的测试（例如只运行当前开发模块的测试，加快反馈速度）。

  • 覆盖率监控：使用工具（如 pytest-cov）检测测试覆盖率。确保核心模块的逻辑皆有测试覆盖，对于 AI 生成的代码尤需如此。如果覆盖率不足，及时补充测试用例（可让 AI 根据代码补写一些测试，但需人工审查其合理性）。

  • 持续集成（CI）：搭建 CI 管道（可使用 GitHub Actions、GitLab CI 等）在每次推送代码或合并 PR 后自动运行整个测试套件。这样即使开发者本人一时疏忽，CI 也能捕捉到问题。在独立项目中，CI 服务器充当“第二双眼睛”，每当 AI 产生代码变更并推送，自动化流程立即验证所有回归测试是否通过。

  • 回归测试：保留所有已通过的测试用例，尤其是过去发现的 bug 案例，形成回归测试集。每次代码更新都运行这些用例以验证旧功能仍正常。这对 AI 反复重构或优化代码的场景非常关键——防止“AI 勤奋改代码，功能不知不觉出问题”。开发者应持续扩充回归测试集，涵盖光学计算的边界情况、设备指令的极端情形等，保障 AI 不会在处理新需求时引入旧问题。

  • 性能和稳定性：除功能正确性外，可加入性能测试或长时间运行测试。例如验证某光学仿真算法在 AI 改写后仍然高效，或设备控制循环跑几个小时不出现资源泄漏。自动化脚本可定期触发这些非功能测试，及时发现潜在问题。

  • 测试报告与分析：配合使用测试报告工具（如 pytest-html 或 CI 内置报告）方便地查看测试结果和趋势。长期观察测试通过率、失败率曲线，关注因 AI 引入变更导致的失败。如果某段时间频繁有测试失败，需要分析 AI 生成代码的问题模式，调整开发策略（例如加强提示工程，或细化测试以约束 AI 行为）。

整体而言，持续验证流程是在为 AI 保驾护航——即便 AI 能快速生成代码，也必须经过严密的自动化测试检验才能正式接受。测试驱动开发已经将质量内建于过程，而持续集成确保每一次演进都不破坏这种质量基准。对于光学科研类应用，其计算结果往往严谨且关系重大，持续验证尤为不可或缺。

7. 模块文档生成：AI 辅助文档编写

高质量的软件离不开完备的文档。在 AI 参与编码过程中，可以同时利用 AI 提升文档编制的效率和质量：

  • 内嵌文档（Docstring）：在 Python 代码中，鼓励为每个模块、类、函数编写 docstring 说明其用途、参数、返回值和示例。开发者可在编写或生成完某段代码后，提示 AI 为其添加规范的 docstring。例如，函数实现完成后，对 AI 说“为以上函数添加 Python 风格的文档字符串”。ChatGPT 擅长根据代码内容生成简明扼要的说明，并能遵循特定格式（如 reStructuredText 用于 Sphinx，或 Google/Numpy 风格）自动填充文档模板。借助 AI 自动生成 docstring 可大幅提高文档编写效率，节省人工时间，同时确保文档与代码同步更新。

  • 自动化 API 文档：配合 docstring 使用文档生成工具如 Sphinx。在项目的 docs 目录下编写 Sphinx 配置，通过 autodoc 从代码提取 docstring 生成 API 文档网页或 PDF。由于 docstring 是 AI 即时从代码生成的，准确描述了函数行为，文档生成后即可对外发布，减少手工编写 API 文档的工作量。确保在 CI 流程中加入文档构建，一旦代码变更合并主分支，即重新生成文档，随时保持最新。

  • 设计方案和原理说明：对于光学建模算法、硬件交互协议等复杂模块，可让 AI 协助撰写更高层次的说明文档。例如 README.md、用户指南、设计白皮书等。开发者提供提纲或要点，AI 据此生成初稿，然后人工润色完善。LLM 模型在根据要点扩写技术文档、举例说明方面有优势，可输出丰富且通俗的讲解。这对于独立开发者而言节省了不少精力，也保证了文档的专业性和可读性。

  • 示例代码与教程：利用 AI 编写使用示例和教程也是可行的。比如要求 AI 基于模块 API，生成一个 Jupyter Notebook 案例，演示如何调用光学仿真库完成某种分析。AI 能快速产出示例代码和相应说明文字，开发者只需调试确认其正确性即可。这些示例有助于最终用户理解和使用软件。

  • 多语言支持：如果应用需要面向不同语言用户，AI 也可以帮助翻译文档。撰写完中文文档后，可让 AI 协助翻译成英文，或反之亦然，保证不同语言版本内容一致。当然，翻译结果需人工抽查专业术语。

通过将 AI 融入文档工作流，独立开发者可以同步“代码即文档”：每个模块的开发伴随文档产出，不欠文档债。ChatGPT 等模型能确保文档内容准确全面、语气专业友好。长期来看，这使项目更具可持续性——哪怕以后维护者更替，有完整文档可依，降低知识流失风险。

8. 项目结构组织建议

一个清晰合理的项目结构是成功的基础。针对光学建模、仿真或设备控制类的 Python 应用，可参考如下的目录模板：

my_optics_project/
├── docs/                   # 文档目录（说明书、API 文档等）
│   └── user_guide.md       # 用户手册示例
├── requirements.txt        # 项目依赖列表
├── setup.py / pyproject.toml  # 项目安装和构建配置
├── src/                    # 源代码目录（或直接以项目名为目录）
│   ├── my_optics_project/  # 项目主包
│   │   ├── __init__.py
│   │   ├── optics.py       # 光学核心算法模块 (如光线追踪、光学计算)
│   │   ├── devices.py      # 设备控制模块 (与硬件交互的接口)
│   │   ├── utils.py        # 工具函数模块 (通用算法、辅助功能)
│   │   ├── models/         # 数据模型子包
│   │   │   └── __init__.py 
│   │   └── ...             # 其他子模块或子包
│   └── tests/              # 测试用例目录
│       ├── __init__.py
│       ├── test_optics.py  # 测试光学算法功能
│       ├── test_devices.py # 测试设备控制功能
│       └── ...             
└── .gitignore              # Git 忽略文件

上述结构中，采用 src/ 目录容纳项目代码，有助于避免包导入混淆，提高安装灵活性。将业务逻辑划分到不同模块/子包，使目录层次清晰地反映软件的领域组成：

  • optics.py 模块负责光学计算核心，实现各类光学模型和算法（如几何光线追踪、衍射计算等）。
  • devices.py 模块封装实验设备的控制逻辑，例如激光器、相机、光学平台等的指令通信，可视需要进一步按设备类型拆分子模块。
  • utils.py 放置通用工具函数，如数值计算辅助、数据格式转换等，这些函数服务于各主模块但独立可复用。
  • models/ 子包定义数据模型和配置，例如光学元件类（透镜、反射镜等）及其属性，实验场景参数类等，用于在不同模块间传递结构化数据。
  • tests/ 目录下每个模块对应至少一个测试文件，确保模块功能都有覆盖。测试代码与源代码分离存放，清晰明了。
  • docs/ 目录用于存放说明文档，既包括手写的 Markdown 指南，也包括 Sphinx 文档源文件。如果采用 Sphinx，可以在 docs 内包含 source/ 和 build/ 子目录等。
  • 配置与脚本：根目录下的 requirements.txt 列出运行所需库（如 numpy、scipy、matplotlib 等），setup.py/pyproject.toml 定义包的元数据和依赖，方便安装发布。如果项目需要提供命令行工具，可在此配置 entry_points。其他诸如 Dockerfile、scripts/ 脚本目录等也可按需加入根目录，用于部署和辅助工具。

良好的项目结构让开发和协作更加顺畅。独立开发者往往后期会引入更多功能，有合理的结构能从容扩展。例如，要增加一个“校准”模块，只需在 src 中新建 calibration.py，添加对应测试 test_calibration.py 并在文档中记录即可。总体而言，目录规划应遵循高内聚、低耦合原则，将相关功能归置一处，不相关的分离。这与前述公理设计方法一脉相承，从架构上保证了模块独立性。

9. 推荐工具链

最后，结合上述流程各环节，建议配套采用一些工具提升效率与质量：

  • BDD 工具：采用 Python BDD 框架如 pytest-bdd 或 behave 实现 Gherkin 场景到测试代码的落地。Cucumber 也有多语言实现，若包含部分 JS 代码也可考虑。但 pytest-bdd 与 Python 生态集成度高，推荐用于编写可执行的场景测试。

  • 测试框架：使用 pytest 作为统一的测试执行框架。其丰富的插件（如 pytest-xdist 并行执行、pytest-cov 覆盖率统计等）可满足持续集成和复杂测试需求。对于性能敏感的光学计算，可引入 pytest-benchmark 做基准测试。

  • 断言与假设：充分利用 pytest 的断言机制以及诸如 Hypothesis 库进行基于性质的随机测试，以探索光学算法在各种输入下的表现，增加对 AI 生成代码的信心。

  • 代码格式化：使用 Black 工具自动格式化 Python 代码，统一编码风格，减少人工调整格式的时间。每次 AI 产出代码后运行 Black，可以立即规范缩进、换行等。搭配 isort 自动整理 imports 顺序。格式化工具确保 AI 生成代码符合 PEP8 规范，使代码整洁一致。

  • 代码静态检查：引入 Flake8 或 Pylint 进行静态代码分析，及时发现语法错误、不规范用法和潜在 bug。对于类型严格的场景，使用 mypy 进行静态类型检查，在代码中加入类型注解（PEP 484）可帮助 AI 理解数据结构，也提高代码可靠性。

  • 版本控制辅助：使用 Commitizen 等工具规范提交信息格式，或 IDE 插件如 AICommit 自动分析代码改动生成清晰的 Git 提交消息。不过自动生成需审慎使用，确保消息准确表达意图。Git GUI 工具（如 SourceTree、GitKraken）可视化地展示分支和提交历史，帮助独立开发者直观管理项目进展。

  • 持续集成/交付：推荐配置 CI 工具（如 GitHub Actions、GitLab CI）实现自动化流程，包括运行测试、代码质量检查、文档构建，甚至打包发布。对光学应用，可进一步结合容器化，如编写 Dockerfile 并在 CI 中构建镜像，确保科研代码在不同环境下运行一致。

  • 文档生成：使用 Sphinx 自动产出开发者文档，配合主题（如 Read the Docs 风格）发布到线上供查阅。如果偏好 Markdown 文档，可采用 MkDocs 搭配 mkdocs-material 主题快速生成美观的文档站点。上述工具都可融入 CI，在代码变更时自动构建更新文档。

  • 其他协同工具：利用项目管理工具（GitHub Projects、Trello 等）跟踪任务，在拆解 FR 到具体实现的过程中管理待办事项，方便与 AI 协作时逐项攻克。对于 AI 产生的异常或 bug，及时记录到 issue 进行跟踪，确保问题被解决且有据可查。

上述工具链大多免费开源，易于集成到个人项目中。通过自动化和 AI 的结合，开发者可以专注于创造性的科研和业务逻辑，而让工具承担重复繁琐的任务。这套工具链也为团队协作预先铺好了道路——一旦项目扩大，有更多开发者加入，这些规范和工具依然适用，不需要临时再去规范化。

总结与展望

综上，本蓝图面向独立开发者，围绕**“公理设计 -> BDD 场景 -> TDD 开发 -> 函数式实践 -> Git 协作 -> 持续测试 -> 文档生成 -> 项目结构 -> 工具链”** 构建了一套 AI 协同开发流程。每一阶段都有清晰的方法论支撑和操作指南：

  • 在分析阶段，用公理设计分解需求，确保模块正交独立，为后续实现打下良好架构基础。
  • 在需求表达上，引入 BDD 使需求以行为案例呈现，减少认知偏差，并为测试驱动奠定基础。
  • 进入开发，严格践行 TDD，通过测试约束 AI 编写代码，形成快速反馈循环，保证功能符合预期。
  • 编码风格上融入函数式编程理念，使 AI 产出的代码更纯净、易测、易组合，提升质量与可维护性。
  • 使用 Git 精细管理版本和分支，人机协同的每一步都有迹可循，降低集成风险并记录演变历史。
  • 以持续集成和回归测试为质量保驾护航，每次代码变更都经过自动验证，建立对 AI 贡献代码的信任。
  • 文档与代码同步生长，AI 帮助将专业知识和实现细节记录下来，实现软件即产品、代码即文档的理想。
  • 项目结构合理规划，模块边界清晰，为功能扩展和团队扩容提供了坚实框架。
  • 辅以现代开发工具链，全方位提升开发效率和代码质量，使 AI 的引入成为加速器而非风险点。

整个流程体现了 “以测试为导向，以协作为核心” 的理念：即使只有一名开发者，人和 AI 也组成了一个团队，需要通过规范的流程和工具来协同工作。光学研发类软件往往复杂精密，这更需要科学的开发方法保证正确性。本蓝图旨在长期指导开发实践，帮助开发者借助 AI 之力又不失工程纪律，在保证质量的前提下大幅提升开发速度。

展望未来，随着 AI 模型能力的提高，这种协同模式将更加普遍和高效。开发者应不断更新知识，尝试新的 AI 辅助工具和方法。但无论技术如何演进，良好的工程原则（如公理设计、TDD、模块化等）仍将是支柱。希望这套蓝图能为您的光学应用开发之旅提供清晰路径，在 AI 的帮助下创造出高质量的科研软件产品。祝您开发顺利，收获成功的项目成果！

AI 协同开发简化流程 （给 LLM 看的“协作说明”）

用途：在与 AI 对话时先贴出这段文字，确保双方遵循同一开发节奏与标准。

  1. 公理设计（Axiomatic Design）

    • 把需求拆成 FR → DP，一一对应，保持低耦合高内聚。

  2. BDD 场景

    • 用 Gherkin 撰写 Given-When-Then 场景文件；
    • 采用 pytest-bdd 或 behave 将场景绑定为可执行测试。

  3. TDD 循环

    1. 先写/更新测试（单元 + 场景）。
    2. 让 AI 编写代码以通过全部测试。
    3. 测试通过后，可指令 AI 重构，但必须保持测试绿灯。

  4. 函数式原则

    • 尽量写纯函数、无副作用、不可变数据；
    • 拆成小函数后再组合，便于 AI 实现与单测。

  5. Git 工作流

    • 分支：main (可发布) → develop (日常集成) → feature/* (单功能)；
    • 小步提交，提交信息遵循 Conventional Commits。

  6. CI / 回归

    • GitHub Actions 自动跑 pytest - -cov + 代码静态检查 + 文档构建；
    • 每次 PR 或合并都要全量测试，防回归。

  7. 文档同步生成

    • 让 AI 为每个模块/函数写 docstring；
    • Sphinx/MkDocs 在 CI 中自动构建 API 与用户文档。

  8. 目录模板

    project/
├─ src/project_pkg/   # 业务代码
├─ tests/             # pytest / BDD 场景
├─ docs/              # Sphinx 或 MkDocs
├─ requirements.txt
└─ pyproject.toml

  9. 工具清单

    • 测试：pytest, pytest-bdd, hypothesis
    • 质量：black, isort, flake8/pylint, mypy
    • 提交：commitizen 或 AICommit
    • 文档：Sphinx + autodoc / MkDocs

使用方法

  1. 把这段流程先发给 AI。
  2. 对每个任务说明：所处阶段、输入测试或场景、期望输出。
  3. 让 AI 遵守上述约定生成/修改代码；如测试不绿灯，返回调整。

这样就能在人机协同下，快速而可控地开发光学研发应用。