不止 Specg2rain 如何用架构与 Docs 驱动 AI Coding需求交给 AI Coding 客户端之后怎样避免“每个功能看似完成整个系统却越来越不稳定”g2rain-member 的核心思路是先建立架构设计和代码规范再持续丰富 Docs让需求开发、需求验证和 README 更新都在同一套工程约束中运行并把每次实践重新沉淀回架构与文档。AI Coding 正在改变软件开发的速度。过去需要开发者逐个查找文件、理解调用链、编写样板代码的工作现在可以由 AI 在较短时间内完成。但速度提升之后一个更重要的问题随之出现AI 怎么知道哪些能力应该实现、哪些边界不能突破又凭什么判断一项需求真的完成了如果输入只有一句“增加手机号换绑功能”AI 很容易得到一份可以编译的代码却未必知道会员身份是否允许转移、逻辑删除记录是否继续占位、租户从哪里取得、哪些接口属于受信内部接口以及变更是否需要数据迁移和调用方协同。问题的根源并不只是需求描述得不够详细。即使每个需求都有一份完整 Spec如果缺少稳定的全局架构与代码规范AI 仍可能针对每次任务选择不同的分层方式、依赖关系、错误模型和数据边界。单个功能局部正确组合起来却形成一套不断漂移的系统。在g2rain-member中我们的核心思想不是“先写 Spec再生成代码”而是建立一个有层次的工程基线第一步架构设计定义系统职责、模块边界、依赖方向和跨服务关系。第二步代码与工程规范定义 API、数据库、安全、测试、依赖和完成标准。第三步持续演进的 Docs沉淀需求、设计、决策、运维知识和项目事实。第四步AI Coding 执行开发、验证与 README 更新。第五步把实践产生的新认知反向补充到架构、规范和 Docs。架构设计回答“这个能力应该属于哪里”代码规范回答“它应该以什么方式进入系统”Spec 回答“这一次具体要实现什么”测试与完成定义回答“怎样证明它完成了”。四者缺一不可。为什么不采用纯粹的 Spec 驱动Spec 驱动开发解决了一个重要问题把自然语言需求变成结构化、可执行和可验收的任务。对于单个功能它能够显著减少 AI 的理解偏差。但 Spec 通常围绕“一次需求”组织。纯粹依赖 Spec而没有稳定的项目级架构和工程规范会暴露几个问题。第一局部最优不等于整体稳定。不同 Spec 可能分别给出合理实现却把类似能力放入不同模块采用不同的事务边界、错误码、数据模型或鉴权方式。随着需求增加系统架构会被一次次局部决策重新塑形。第二容易形成“糊墙式开发”。哪里出现需求就在哪里补一段代码哪里暴露问题就继续增加条件和适配层。每次修改都能解决眼前问题却缺少对领域归属、依赖方向、长期演进和重复模式的统一判断。时间久了代码像在旧墙上不断覆盖新材料局部看起来完整内部结构却越来越难以解释。第三非功能约束容易被重复描述或直接遗漏。租户隔离、日志脱敏、内部接口访问控制、依赖治理、数据库迁移、可观测性和回滚策略不应该依赖每一份 Spec 都重新想起。它们需要成为项目的常驻规则。第四需求结束后知识容易散失。如果 Spec 只服务于当次生成代码合并后没有同步更新架构、规范、运维文档和项目入口下一次 AI 仍要重新猜测当前系统。旧 Spec 甚至可能继续描述已经被后续变更替代的局部事实。因此g2rain-member 并不否定 Spec而是给 Spec 增加一个稳定的上层结构架构与规范决定系统的长期方向。Spec 描述一次需求的目标与边界。实现与验证检验两者是否一致。Docs 吸收变更后的新事实。Spec 不再是一面可以随处施工的墙而是一块需要安装到既有建筑结构中的构件。两种方式的差异很清晰。看出发点纯 Spec 关注“当前需求要生成什么”g2rain 更关注“当前需求如何进入既有系统”。看架构纯 Spec 容易让每次需求局部决定结构g2rain 要求先遵循系统职责、模块与依赖边界。看代码风格纯 Spec 更依赖当次提示和模型选择g2rain 统一遵循 API、数据库、安全与代码规范。看质量判断纯 Spec 主要核对需求验收项g2rain 同时验证需求、架构、安全、测试与交付。看知识沉淀纯 Spec 容易停留在当次任务g2rain 持续回写需求、设计、ADR、运维与规范。看长期结果前者可能形成补丁叠加和架构漂移后者则在稳定基线中持续演进。三个流程既消费 Docs也反向完善 Docs在架构设计和代码规范的基线之上整套机制围绕三个主要流程展开需求开发 → 需求验证 → README 更新。每个阶段都要反向丰富架构、规范与 Docs并成为下一次开发的新基线。这三个流程共同构成了一条从业务意图到代码事实再到项目认知的可追溯链路。它不是单向流水线开发中发现的新领域规则、验证中暴露的架构缺口、README 更新时发现的文档漂移都要回写到 Docs必要时更新架构说明、代码规范或 ADR。Docs 不是附件而是 AI Coding 的项目上下文g2rain-member是 g2rain 平台的会员主数据与外部身份绑定服务。它维护租户内会员、稳定会员编号以及企业微信、手机号等外部身份关系并为可信接入渠道提供会员解析与幂等创建能力。项目并不是先从某一份需求 Spec 开始而是先明确会员服务在整个平台中的位置再设计模块边界和代码组织方式。需求只有在这个基础上才能被判断应该由哪个服务、哪个模块和哪一层负责。项目采用三层 Maven 模块模块依赖方向为g2rain-member-startup → g2rain-member-biz → g2rain-member-api。api发布稳定契约biz实现 Controller、Service、DAO 和领域规则startup负责 Spring Boot 启动、配置、观测与镜像组装。会员领域还包含租户隔离、事务、并发幂等、身份唯一性、逻辑删除占位和资料最小化等约束。它同时需要与 IAM、Gateway 和企业微信接入模块协作却不能越界承担登录、Token 签发、回调解密或下游订单业务。这些信息如果只存在于开发者脑中AI 很难稳定执行。因此项目用一组分层文档表达不同类型的事实AGENTS.mdAI Coding 执行入口。docs/project.yaml机器可读的项目元数据与架构规则。docs/requirements需求目标、非目标与验收条件。docs/architecture模块、依赖和运行边界。docs/development代码、API、数据库、测试和完成定义。docs/security调用、租户、身份与数据安全边界。docs/operations配置、部署、观测和故障排查。docs/design具体领域专题设计。docs/decisions长期架构决策记录。README.md面向项目访问者的摘要入口。根目录的AGENTS.md不重复保存完整规范而是告诉 AI Coding 客户端应该按什么顺序读取 Docs、实现过程中遵守什么约束、完成前执行哪些检查。真正的事实来源仍然位于docs。这样做的一个直接好处是开发者与 AI 读取的是同一套规则不需要在每次对话里重新解释整个项目。更重要的是新需求不能绕过架构和规范单独定义自己的开发方式。流程一需求开发——先定义范围再让 AI 修改代码需求开发流程的起点不是打开代码也不只是孤立地写一份 Spec而是先确认当前架构与规范是否足以承载需求再把需求写成可执行、可验收的上下文。对于新增 API、身份类型、跨服务流程、数据库结构变化以及涉及事务、并发、幂等、权限或敏感信息的需求g2rain-member 要求在编码前创建需求文件统一保存在 docs/requirements 目录并使用功能名称命名。一份需求文档至少要回答以下问题为什么需要这项能力目标结果是什么本次明确不处理什么如何防止范围扩张谁在什么条件下触发主流程怎样运行输入、输出和字段语义是什么唯一性、状态、租户、事务、幂等和并发规则是什么调用者是谁信任从哪里建立哪些信息属于敏感数据是否改变表、字段、索引、API、错误码或调用方契约异常怎样返回是否允许重试需要什么日志与告警怎样发布和回滚哪些结果可以通过测试或观测明确验收其中“非目标”和“验收条件”尤其重要。非目标告诉 AI 什么不能擅自扩展。例如一次会员身份变更不代表可以顺手修改 IAM 的登录模型也不代表可以增加未经授权的跨项目接口。验收条件则必须是可以测试或观察的结果不能只写“功能正常”“体验良好”。有了需求文档AI Coding 客户端会从AGENTS.md进入项目依次读取project.yaml、架构总览、模块与依赖边界、代码规范、测试策略、完成定义以及本次需求涉及的专题文档。如果需求影响 API、数据库、安全、依赖或运行配置还要继续读取对应规范。如果现有架构无法合理承载需求正确动作不是把代码硬塞进最方便的模块而是先显式提出架构调整说明为什么改变、影响哪些模块和调用方、是否需要 ADR以及如何兼容和迁移。架构调整获得明确结论后才进入实现。随后AI 才开始分析代码落点AI 的分析顺序是需求目标与非目标 → 架构、API、数据库与安全约束 → 现有源码、POM、配置、SQL 和测试 → 影响范围与实施计划 → 代码、测试、架构与相关文档同步变更。项目还为 AI 提供“参考实现路径”。例如开发企业微信会员解析相关能力时可以按 API、Request、Controller、Service、实现类和测试的顺序阅读现有代码理解薄 Controller、事务、身份查询、唯一键冲突回查和资料白名单等模式。参考实现只用来帮助理解项目惯例不能被机械复制。新的 CRUD 代码即使由生成器产生也仍然需要根据需求补充权限、租户、状态、事务、幂等、敏感字段过滤和测试。开发过程中形成的新规则也不能只留在实现里。如果发现新的错误语义、数据不变量、调用边界或可复用模式需要同步丰富需求文档、专题设计、代码规范或 ADR。这使需求开发从“让 AI 猜项目应该怎么写”转变为“让 AI 在明确范围和现有架构中完成实现并用实践继续完善项目知识”。流程二需求验证——代码生成不等于需求完成AI Coding 很容易产生一种错觉文件已经修改、项目能够编译需求似乎就完成了。g2rain-member 通过测试策略和 Definition of Done把“完成”定义成一组可以逐项检查的条件。首先是分层测试。Domain 层重点验证纯业务规则、边界值、确定性与非法输入。Service 层重点验证状态、事务、幂等、并发冲突和租户一致性。DAO 与 Mapper 层重点验证 SQL、分页、逻辑删除、唯一键和数据隔离。API 与 Controller 层重点验证参数、路由、响应、错误码和访问入口。Startup 层重点验证 Bean 组装、配置绑定、Mapper 扫描和 profile 启动。单元测试不能用 Mock 推断所有事情。只要需求涉及 SQL、事务、唯一键或框架配置就应该由集成测试验证真实行为。以企业微信首次识别会员为例验证不能只覆盖“创建成功”还需要包含已有有效身份返回原会员首次识别在同一事务中创建会员与身份并发唯一键冲突后回滚并回查已删除身份拒绝自动创建或转移会员冻结、删除、缺失或跨租户时返回明确结果externalUserId只去除首尾空白不改变大小写请求、身份与会员的organId始终一致日志、响应和持久化数据不泄露非必要资料。其次是架构与变更审核。验证不只判断需求是否通过还要判断实现是否保持了系统结构。AI 需要结合当前源码、POM、配置和 Git Diff 动态检查模块是否仍遵循startup → biz → apiController、Service、DAO、Domain 和 Converter 是否各守职责API 是否引入了实现层或不必要的运行时依赖是否出现生成器误覆盖、调试代码、无关格式化或敏感信息数据库、配置、启动类、端口和文档声明是否一致Markdown 相对链接与project.yaml必需文档是否完整最后执行项目完整验证命令mvn clean verify。完成定义还要求 AI 回到最初的需求文档逐项核对目标、非目标和验收条件。只有代码、测试、架构、安全、文档和交付要求都满足需求状态才能从“开发中”推进到“已完成”。如果验证过程中反复出现同类缺陷例如多个需求都遗漏跨租户测试说明问题不只在当前实现测试规范或完成定义本身也需要补充。验证阶段因此也是架构与 Docs 的反馈机制而不是一次性的质量闸门。这里还有一条非常重要的诚实边界需要真实数据库、测试环境、外部服务或人工验收的事项如果没有实际执行AI 不能声称已经验证。最终报告必须列出执行过的命令、测试结果、未执行项及剩余风险。AI 不只是写代码也要对“我们究竟验证了什么”负责。流程三README 更新——只发布经过验证的项目事实README 是开发者第一次进入项目时看到的入口但它不应该承担全部需求和设计细节。在 g2rain-member 中README 只保留四类内容项目定位与职责边界核心领域、系统关系与模块摘要可以直接执行的快速开始指向完整 Docs 的导航。需求开发和验证完成后AI 会根据 Git Diff 判断 README 是否受到影响。例如下列变化通常需要同步更新 README项目新增或移除了核心能力Maven 模块、依赖方向或系统调用关系改变JDK、Spring Boot、基础设施或构建方式改变启动命令、默认端口、环境要求或部署入口改变新增开发者必须了解的重要流程或文档入口。README 的内容不直接从对话临时生成而是从已经验证的事实中映射。project.yaml 提供项目定位、模块、命令和社区信息。architecture 文档提供系统关系与架构摘要。development 文档提供环境、构建、测试与开发入口。operations 文档提供配置、运行与部署信息。requirements 和 design 文档提供已经交付的核心能力说明。Git Diff 用来判断本次需要同步哪些变化。复杂的“为什么”仍然保留在专题设计或 ADR 中。例如会员编号为什么采用M Base36(member.id)已删除身份为什么永久占位并发冲突为什么必须回滚后回查都不需要在 README 中完整展开。README 的任务是提供一张可信地图而不是复制整个知识库。更新后AI 还要再次核对 README 中的模块、版本、命令和链接是否与当前仓库一致。于是 README 更新不再是开发结束后的随手补充而是需求交付流程的最后一环。这个过程也会反向暴露文档问题如果 README 找不到可靠的项目定位、启动命令或能力来源通常意味着project.yaml、架构文档或运维文档还不完整。正确做法不是直接在 README 中猜一个答案而是先补全对应事实来源再生成摘要。三个流程如何形成闭环把三个流程放在一起可以看到架构与 Docs 在 AI Coding 中承担了不同角色。需求开发阶段架构与规范是边界需求 Docs 定义目标、非目标和验收条件。需求验证阶段Docs 是标尺用来验证功能正确性、架构一致性和工程完整性。README 更新阶段Docs 是事实来源用来输出经过实现与验证的项目摘要。每个阶段结束后还要把新规则、新决策和新事实继续沉淀回 Docs。流程结束后更新过的需求、架构、开发、安全和运维文档又会成为下一次 AI Coding 任务的上下文。项目不是靠一份永远不变的“大设计”冻结架构而是在稳定原则下通过每次真实需求不断校正和丰富架构。这也是为什么AGENTS.md只作为入口而不复制完整规则如果执行入口、需求模板、架构规范和完成定义各自维护一套事实新的文档漂移很快又会出现。让所有流程回到同一个docs体系才可能持续保持一致。结语让 AI 参与交付而不只是参与编码真正可靠的 AI Coding不只是更快地产生代码也不是把每个需求转换成 Spec 后逐个生成。它需要先拥有一个可以被读取和检查的架构基线理解统一的代码与工程规范然后再处理具体需求验证功能和架构是否同时成立诚实报告未验证事项并把最终结果同步回项目文档。g2rain-member 的实践可以概括为一句话架构决定方向规范建立秩序Spec 描述变化代码承载实现测试证明结果Docs 沉淀演进README 发布已经验证的项目事实。与纯粹的 Spec 驱动相比这套方式多了一层长期约束也多了一条持续反馈路径。它避免每个需求重新发明架构减少局部补丁不断叠加的“糊墙式开发”让系统在快速变化中仍然保有可以解释、可以审核、也可以继续演进的整体结构。当架构设计、代码规范、需求开发、需求验证和 README 更新被连接成同一条链路AI Coding 客户端才从一次性的代码生成工具转变为能够参与完整软件交付和架构演进的工程协作者。关于 g2raing2rain 致力于构建开放、清晰、可演进的企业级技术平台。项目官网https://www.g2rain.comGitHubhttps://github.com/g2rain欢迎通过 Issues、Discussions 和 Pull Request 参与项目建设。