# behavior-preserving-simplified-implementation **Repository Path**: luminousone/behavior-preserving-simplified-implementation ## Basic Information - **Project Name**: behavior-preserving-simplified-implementation - **Description**: Behavior-Preserving Simplified Implementation (BPSI): an experimental methodology for AI-assisted software engineering. - **Primary Language**: Unknown - **License**: CC-BY-4.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-16 - **Last Updated**: 2026-09-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 行为保持型降级实现:一种面向 AI 软件工程的可执行原型方法 > **Behavior-Preserving Simplified Implementation (BPSI)** > **提出者:王羿衡(Wang Yiheng)** > **首次公开版本:v0.1.0** > **首次公开日期:2026-09-09** > 状态:**实验性软件工程方法提案 / Experimental Software Engineering Proposal** > 核心思想:**降低实现复杂度,而不是降低需求完整度。** > [!IMPORTANT] > 本仓库公开记录的是 **BPSI 这一命名、定义和结构化方法提案的首次公开版本**。它不声称“历史上从未有人提出过任何相似思想”,也不声称已经通过充分实验验证。BPSI 与原型开发、Specification by Example、BDD、Mock-First、API Design-First、Spec-Driven Development 等既有实践存在明确继承关系,方法价值应通过公开 Benchmark 和可复现实验继续验证。 ## 快速导航 - [方法规范](docs/METHODOLOGY.md) - [起源、范围与优先权声明](docs/ORIGIN_AND_SCOPE.md) - [局限性与不适用场景](docs/LIMITATIONS.md) - [评估协议](docs/EVALUATION.md) - [参考与相关工作](docs/REFERENCES.md) - [路线图](ROADMAP.md) - [贡献指南](CONTRIBUTING.md) - [引用方式](CITATION.cff) - [v0.1.0 发布说明](RELEASE_NOTES_v0.1.0.md) ## 摘要 随着 AI 编程工具逐渐从代码补全走向 Agent 式开发,一个越来越明显的问题是:AI 能快速写出大量代码,但当一个任务同时包含 UI、交互、业务规则、数据库、权限、缓存、消息队列、外部服务、部署和测试时,模型需要在一次任务中替人做出过多尚未确定的设计决策。结果往往不是“不会写代码”,而是需求漂移、状态不一致、架构过度设计、返工增加,以及不同会话之间对同一需求产生不同理解。 本文提出一种面向 AI 软件工程的工作方法:**行为保持型降级实现(Behavior-Preserving Simplified Implementation, BPSI)**。 BPSI 主张,在正式工程化之前,先把复杂系统主动映射为一个**低基础设施复杂度、但尽量保留核心用户行为和业务规则的可执行版本**。对于 Web/业务型软件,这个版本可以是 HTML/CSS/JavaScript + Mock Data + localStorage/IndexedDB;对于 API、分布式、算法或嵌入式系统,也可以分别使用 Mock Server、状态机、仿真器或参考实现。 这个“降级版本”不是一次性原型,而是后续工程实现的 **Executable Behavioral Baseline(可执行行为基线)**。在行为确认后,再逐层恢复数据库、真实 API、身份认证、消息系统、外部服务、性能、安全、可观测性和部署能力,并通过自动化测试验证正式实现没有偏离已经确认的行为。 BPSI 不试图替代 Spec-Driven Development(SDD)、Test-Driven Development(TDD)、BDD、API Design-First 或 Specification by Example。它更像是在“规格”和“正式工程实现”之间增加一个**可运行、可观察、可验证的行为层**。 --- ## 1. 问题:AI 软件开发的瓶颈不只是代码生成 传统的 AI 编程请求经常长这样: ```text 帮我做一个完整系统: - 用户注册登录 - 权限管理 - 文件上传 - 消息通知 - 后台管理 - 数据库 - Redis - 部署 - 测试 ``` 这类请求的问题不是 AI 不会分别实现这些功能,而是它需要同时决定: - 页面和交互应该怎样设计; - 用户状态如何变化; - 业务规则有哪些; - 数据模型如何组织; - API 如何划分; - 权限在哪里校验; - 哪些数据应该缓存; - 哪些操作需要事务; - 是否需要消息队列; - 如何处理异常; - 测试应该覆盖什么; - 最终如何部署。 这些未决问题共同构成了一个很大的**设计不确定性空间**。 本文提出一个工程假设: > **在其他条件相近时,一次交给 AI 的未决设计问题越多,生成结果出现漂移、不一致和返工的概率越高。** 这不是数学定律,而是 BPSI 希望通过实验验证的工程假设。 因此,与其试图通过越来越长的 Prompt 一次性描述完整系统,不如主动减少 AI 每一阶段需要猜测的内容。 --- ## 2. 定义:什么是“行为保持型降级实现” **行为保持型降级实现(BPSI)**是指: > 在尽量保持核心业务规则、用户流程、可观察状态和输入输出行为的前提下,主动降低基础设施、架构和运行环境复杂度,构建一个低成本、可执行、可验证的参考实现;随后以该实现作为行为基线,逐层恢复正式工程能力。 这里最重要的一句话是: > **降级的是实现复杂度,不是需求质量。** > [!NOTE] > 这里的“降级实现”是**开发阶段的简化建模**,不是生产系统在故障、过载时使用的服务降级(fallback / graceful degradation)。两者目的和发生阶段不同。 例如,一个生产系统可能使用: ```text React ↓ REST API ↓ OAuth / RBAC ↓ Spring Boot ↓ Redis ↓ PostgreSQL ↓ Kafka ↓ Object Storage ``` 在 BPSI 的行为原型阶段,它可能被暂时映射为: ```text HTML / CSS / JavaScript ↓ Local State ↓ Mock User / Role Switcher ↓ localStorage / IndexedDB ↓ Synchronous Event Stub ↓ Blob / Local Fixtures ``` 复杂度显著降低,但下面这些内容仍应尽可能完整: - 用户能做什么; - 用户不能做什么; - 操作顺序; - 页面状态; - 表单校验; - 业务规则; - 成功/失败反馈; - 关键状态转换; - 权限结果; - 对外可观察的输入与输出。 --- ## 3. BPSI 的三个核心原则 ### 3.1 Behavior First:先固定行为,再恢复架构 正式技术栈不是最先确定的东西。 首先确认: ```text Given 用户处于什么状态 When 用户进行了什么操作 Then 系统应该表现为什么结果 ``` 一个被确认的用户流程应该可以被实际点击、运行和观察,而不仅仅存在于自然语言里。 ### 3.2 Simplify Infrastructure, Preserve Semantics 可以替换基础设施,但不能随意改变语义。 例如: | 正式能力 | 降级实现 | 应保留 | 暂不声称保留 | |---|---|---|---| | PostgreSQL | localStorage / IndexedDB | CRUD、字段、校验、状态 | 事务隔离、并发一致性 | | OAuth / RBAC | Mock User / Role Switcher | 不同角色的允许/拒绝结果 | Token 安全、会话安全 | | Kafka / RabbitMQ | 同步事件模拟器 | 事件触发关系 | 重试、乱序、重复投递 | | S3 / OSS | Blob / 本地 Fixture | 上传和读取流程 | 持久性、吞吐、容灾 | | Elasticsearch | 本地数组过滤 | 查询交互和结果格式 | 排名、索引性能 | | 第三方支付 | Fake Adapter | 支付状态机 | 真实资金结算 | 因此,BPSI 不会声称一个静态网页“模拟出了 PostgreSQL 的事务能力”。 它只要求原型明确:**哪些语义已经被验证,哪些工程性质仍然欠账。** ### 3.3 Baseline Before Upgrade 一旦原型经过确认,它就不再只是 Demo,而是一个 **Behavioral Baseline**。 后续升级必须回答: > 新实现是否仍然满足旧版本已经确认的可观察行为? 而不是: > 新代码看起来是不是更高级? --- ## 4. 推荐流程 ```mermaid flowchart TD A[Intent / Product Spec] --> B[Complexity Mapping] B --> C[Simplified Executable Implementation] C --> D[Human / AI Behavior Review] D --> E[Behavioral Baseline] E --> F[Acceptance Tests] E --> G[API / Data Contracts] E --> H[Non-functional Gap Ledger] F --> I[Production Architecture Plan] G --> I H --> I I --> J[Progressive Engineering Restoration] J --> K[Behavior + Contract + NFR Verification] K --> L[Production System] ``` ### Phase 0:Intent 先回答“要解决什么问题”,而不是“用什么框架”。 产物可以是: ```text spec.md ``` 至少包含: - 用户角色; - 用户目标; - 核心场景; - 业务约束; - 输入与输出; - 异常情况; - 暂不实现的范围。 --- ### Phase 1:Complexity Mapping 把生产系统需要的复杂能力列出来,然后为行为原型寻找低复杂度替代。 例如: ```text PostgreSQL -> IndexedDB OAuth -> Role Switcher REST API -> JavaScript Adapter S3 -> Blob URL Kafka -> Event Stub Email Provider -> Fake Inbox Payment -> Payment Simulator ``` 这一阶段的目的不是选择最终架构,而是回答: > **为了验证核心行为,我们最少需要什么?** --- ### Phase 2:Simplified Executable Implementation 构建可执行版本。 对于典型 Web 软件,可以优先使用: ```text HTML CSS JavaScript / TypeScript Mock Data localStorage / IndexedDB ``` 这里的静态网页不是“设计稿”。 它应该尽量具备: - 页面导航; - 表单; - 数据变化; - 错误状态; - Loading 状态; - 空状态; - 权限状态; - 操作反馈; - 业务流程; - 关键状态机。 换句话说: > Figma 回答“它长什么样”,BPSI 原型还应回答“它运行起来是什么行为”。 --- ### Phase 3:Behavior Review 由人实际运行。 检查: - 用户能否完成目标; - 操作顺序是否合理; - 是否遗漏状态; - 是否出现互相矛盾的规则; - 权限是否符合预期; - 异常流程是否完整; - 字段是否足够; - 是否存在不必要功能。 这个阶段修改成本通常远低于正式后端已经完成以后再返工。 --- ### Phase 4:Freeze the Behavioral Baseline 确认后的原型进入“基线”状态。 需要记录: ```text behavior/ scenarios.md state-machine.md permissions.md ``` 推荐用 Given / When / Then 描述关键行为: ```gherkin Given 用户当前没有正在进行的学习记录 When 用户点击“开始学习” Then 创建一条进行中的记录 And 页面进入计时状态 And “开始学习”按钮不可再次触发 ``` 此时,原型 + 行为描述共同构成可执行行为规范。 --- ### Phase 5:Turn Behavior into Tests and Contracts 这是 BPSI 从“原型方法”变成“工程方法”的关键一步。 将已经确认的行为逐步转换为: ```text E2E Tests Acceptance Tests API Contracts Data Schemas State Machine Tests ``` Web 系统可以使用 Playwright 等工具,把真实用户操作转化为端到端测试。 API 可以采用 OpenAPI 的 Design-First 思路,先固定接口契约,再实现服务器。 于是: ```text 原型行为 ↓ 验收测试 ↓ API Contract ↓ 正式实现 ``` 最终真正约束正式系统的,不只是“记得参考那个 Demo”,而是一组机器可以持续执行的规则。 --- ### Phase 6:Non-functional Gap Ledger 静态或简化实现无法证明很多生产性质。 因此项目必须显式维护一个: ```text non-functional-gaps.md ``` 记录尚未验证的工程能力,例如: - 并发; - 性能; - 数据一致性; - 事务; - 安全; - 隐私; - 容灾; - 可观测性; - 重试; - 幂等; - 限流; - 可维护性; - 成本。 例如: ```markdown | Capability | Prototype | Production Requirement | Status | |---|---|---|---| | Authentication | Mock role | OAuth2 + secure session | Pending | | Persistence | IndexedDB | PostgreSQL + backup | Pending | | Concurrency | Not modeled | 1000 concurrent users | Pending | | Audit | UI history only | Immutable audit log | Pending | ``` 这一步防止团队产生一个危险错觉: > “原型能跑,所以系统已经被验证了。” BPSI 验证的是**行为的一部分**,而不是自动验证全部非功能需求。 --- ### Phase 7:Progressive Engineering Restoration 不要从原型直接跳到“最终大型架构”。 逐层替换: ```text V0 Static Behavior Prototype V1 Local Persistence V2 Mock API Boundary V3 Real Backend V4 Real Database V5 Authentication / Authorization V6 External Services V7 Cache / Queue / Search V8 Security / Observability / Performance V9 Production ``` 每次替换一层,都运行原有行为测试。 原则是: > **架构可以升级,已确认的行为不能无意漂移。** --- ## 5. 与 Spec-Driven Development 的关系 GitHub Spec Kit 当前的核心 SDD 流程是: ```text Specify ↓ Plan ↓ Tasks ↓ Implement ↓ Converge ``` BPSI 不与它竞争。 一个组合流程可以是: ```text Specify ↓ Behavior Simplification ↓ Executable Prototype ↓ Behavior Review ↓ Behavioral Baseline ↓ Acceptance Tests / Contracts ↓ Plan ↓ Tasks ↓ Production Implementation ↓ Converge against Spec + Baseline + Tests ``` SDD 重点解决: > **“AI 应该依据什么明确意图进行开发?”** BPSI 进一步尝试解决: > **“在正式架构出现之前,能否先让需求以一个可运行的形式被验证?”** 二者是互补关系。 --- ## 6. 与已有软件工程思想的关系 BPSI 并不是凭空出现的。 它吸收并重新组合了多种已有实践。 ### Specification by Example 用具体例子约束抽象需求,减少双方对文字的不同理解。 BPSI 进一步要求: > 关键例子不仅写下来,而且尽可能先运行出来。 ### BDD / Given-When-Then 适合把原型行为变成结构化验收条件。 ### API Design-First OpenAPI 等方法强调在服务实现之前定义接口契约。 BPSI 建议:在 UI/行为基线确认之后,把系统边界进一步固化成 API Contract。 ### Mock-First 通过 Mock 隔离暂时不存在的依赖。 BPSI 将 Mock 从局部测试技术提升为整个“降复杂度阶段”的重要手段之一。 ### End-to-End Testing E2E 测试验证用户真实可观察行为。 在 BPSI 中,E2E Test 是从“可点击原型”迁移到“正式工程”的桥梁。 --- ## 7. BPSI 与普通原型最大的区别 普通原型常见生命周期: ```text 做 Demo ↓ 评审 ↓ 丢掉 ↓ 重新开发 ``` BPSI 希望变成: ```text 做可执行行为原型 ↓ 确认行为 ↓ 生成行为基线 ↓ 提取验收测试 / Contract ↓ 逐层替换简化实现 ↓ 持续验证行为 ``` 因此 BPSI 原型不是一次性的 UI Demo。 它承担四种角色: 1. **需求探索工具** 2. **可执行行为规范** 3. **AI 上下文锚点** 4. **正式实现的验收基线** --- ## 8. 为什么这种方法可能特别适合 AI AI 对“局部、明确、有即时反馈”的任务通常比“同时完成大量开放式设计决策”的任务更容易收敛。 以 Web 系统为例,简化版本具有: - 运行环境简单; - 依赖少; - 修改反馈快; - 用户行为直接可见; - 状态容易构造; - Mock 数据容易生成; - 错误容易定位; - AI 可以快速重复迭代。 因此 BPSI 的重点不是: > “静态网页比后端高级。” 而是: > **先把问题转换成 AI 更容易获得反馈和验证的表示形式。** 之后再恢复工程复杂度。 可以把它理解为: ```text High-Uncertainty Problem ↓ Low-Complexity Executable Representation ↓ Validated Behavior ↓ Machine-Checkable Contracts ↓ Production Engineering ``` --- ## 9. 什么时候不应该直接使用静态 Web 原型 BPSI 不等于“任何软件都先写网页”。 静态 Web 特别适合: - 管理系统; - SaaS; - 内容平台; - 工作流系统; - 表单系统; - 电商前后台; - 学习/效率工具; - 大多数 CRUD + Workflow 产品。 但对于下面的系统,应更换“降级载体”: | 系统 | 更合适的降级实现 | |---|---| | API 平台 | OpenAPI + Mock Server | | 分布式系统 | 状态机 + 模拟器 + Contract Test | | 数据处理系统 | 小数据集 + Reference Pipeline | | 算法系统 | Python Reference Implementation | | 嵌入式系统 | Simulator / Hardware Stub | | 游戏 | Gray-box Prototype | | 实时系统 | Deterministic Simulation | | 编译器 | Minimal Interpreter / Reference Parser | 以下领域尤其不能把静态原型当成充分验证: - 安全关键系统; - 医疗关键系统; - 金融核心账务; - 密码学; - 高并发一致性系统; - 强实时系统; - 硬件时序系统。 这些领域仍可以使用“行为保持型简化”的思想,但必须加入更严格的模型、验证和测试方法。 --- ## 10. 给 AI Agent 的推荐约束 当行为基线形成以后,可以给 Agent 一个明确规则: ```text The executable prototype is the behavioral reference for user-visible flows. Do not redesign confirmed behavior unless the specification explicitly changes. When replacing mock/local infrastructure with production components: 1. preserve observable behavior; 2. preserve validation rules; 3. preserve state transitions; 4. preserve permission outcomes; 5. add tests before removing the simplified implementation. If production constraints require a behavior change, report the conflict before changing it. ``` 仓库中还可以维护: ```text .github/copilot-instructions.md AGENTS.md specs/ behavior/ prototype/ tests/e2e/ contracts/ ``` 让不同 AI Agent 都能获得相对稳定的工程上下文。 --- ## 11. 推荐仓库结构 ```text project/ ├── README.md ├── AGENTS.md ├── .github/ │ └── copilot-instructions.md ├── specs/ │ └── product-spec.md ├── prototype/ │ ├── index.html │ ├── app.js │ └── data/ ├── behavior/ │ ├── scenarios.md │ ├── state-machine.md │ └── permissions.md ├── contracts/ │ └── openapi.yaml ├── tests/ │ └── e2e/ ├── architecture/ │ ├── production.md │ └── non-functional-gaps.md └── src/ ``` --- ## 12. 如何验证这套方法到底有没有价值 BPSI 不应该只靠“感觉更好”。 建议做对照实验。 选择 3~5 个中等复杂度项目,例如: - Todo / 项目管理系统; - 学习记录系统; - 小型商城; - 工单系统; - 内容管理系统。 ### Group A:Direct-to-Production ```text Requirement ↓ AI directly builds full stack ``` ### Group B:BPSI ```text Requirement ↓ Simplified executable implementation ↓ Behavior baseline ↓ Tests / contracts ↓ Production implementation ``` 比较: | 指标 | 说明 | |---|---| | Feature Pass Rate | 需求通过率 | | Behavioral Regression Count | 行为回归数量 | | Human Intervention Count | 人工纠错次数 | | Requirement Drift | 实现偏离需求的程度 | | Rework Commits | 返工提交数量 | | E2E Pass Rate | 端到端测试通过率 | | Token / Agent Cost | AI 使用成本 | | Time to First Validated Flow | 首个可验证流程耗时 | | Time to Production | 最终交付时间 | | Architecture Defect Count | 工程设计问题数量 | 如果 BPSI 只让“前期看起来更舒服”,但最终成本、缺陷和返工没有改善,那么这个方法就应该被修正。 如果它在多种 Agent、技术栈和项目中都能降低行为漂移与返工,那么才有资格逐步从“方法提案”发展成更成熟的工程实践。 --- ## 13. 一个更完整的判断标准 一个 BPSI 项目不应以“静态页面做完了”为完成。 真正的完成条件应该是: ```text Intent is documented + Core behavior is executable + Behavior is reviewable + Acceptance criteria are machine-checkable + Production gaps are explicitly tracked + Infrastructure is progressively restored + Behavior remains converged + Non-functional requirements are verified ``` --- ## 14. 一句话总结 > **先用最低必要复杂度把正确的软件行为运行出来,再用工程化逐层替换它,而不是让 AI 一开始同时猜产品、交互、架构和实现。** 这就是行为保持型降级实现(BPSI)的核心。 --- ## 与现有实践的关系与参考 BPSI 是一个组合型方法提案,不声称替代或原创已有软件工程基础思想。它主要受以下实践启发: - GitHub Spec Kit / Spec-Driven Development https://github.com/github/spec-kit https://github.github.io/spec-kit/ - GitHub Copilot Repository Custom Instructions / `AGENTS.md` https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions - Martin Fowler — Specification by Example https://martinfowler.com/bliki/SpecificationByExample.html - Martin Fowler — Given When Then https://martinfowler.com/bliki/GivenWhenThen.html - Thoughtworks — Spec-driven development https://www.thoughtworks.com/insights/blog/agile-engineering-practices/spec-driven-development-unpacking-2025-new-engineering-practices - Swagger — Design-First API Development https://swagger.io/blog/code-first-vs-design-first-api/ - Playwright — Best Practices / Test User-visible Behavior https://playwright.dev/docs/best-practices --- ## 项目定位 目前 BPSI 应被视为: > **An experimental software engineering proposal for AI-assisted development.** 当前版本提出的是**可验证的工程假设和工作流**,不是已经建立的行业标准。欢迎通过案例、反例、Benchmark、Issue 和 Pull Request 对它进行验证、修正或否定。 一个有价值的软件工程方法不应该依赖作者的说服力,而应该能够被重复实验。 --- ## 作者与首次公开记录 - **提出者:** 王羿衡(Wang Yiheng) - **首次公开版本:** v0.1.0 - **首次公开日期:** 2026-09-09 - **项目状态:** Experimental Proposal 关于“首次公开”“提出者”和已有相关工作的边界,请阅读 [Origin & Scope](docs/ORIGIN_AND_SCOPE.md)。 ## 引用 GitHub 会读取仓库根目录的 [`CITATION.cff`](CITATION.cff)。如果你讨论、复现或扩展 BPSI,建议引用本仓库及对应 Release。未来若发布 DOI,将在 `CITATION.cff` 和 Release 中补充。 ## 许可 - 方法论文档、文字和图表:**CC BY 4.0**。 - `examples/` 中的示例代码:**MIT License**。 许可保护的是具体文字、图表和代码表达;抽象思想、方法和适用的知识产权边界请按所在地法律理解。本仓库的许可说明不构成法律意见。