企业官网建设流程全解析

本文提供一套可直接落地到团队项目的 AI Agent 协作规范模板，覆盖代码风格、单元测试、文档治理、开发流程、质量门禁等核心维度。团队可基于此模板结合自身技术栈进行裁剪和落地。

一、总览与适用范围

本文档定义了项目中 AI Agent 参与研发时必须遵守的协作规则，旨在确保：

• 代码风格统一，质量可预期
• 单元测试有明确的边界和门禁
• 文档体系结构化、可追溯
• 开发流程有节奏，review 有章法
• 质量问题可跟进、可闭环

适用对象

• 所有使用 AI Agent（如 Claude、Codex、OpenCode 等）参与编码的项目
• 前端 / 后端 / 全栈项目均可复用，按技术栈做少量适配

二、规范分层（Source Of Truth）

项目中所有规则按"单一可信源"原则维护，避免重复定义和漂移：

核心原则：

1. 三份协作规则文件（AGENTS / CLAUDE / GEMINI）内容必须保持一致，仅标题不同
2. 协作规则文件只维护流程、门禁和约束，不重复代码风格细则
3. 质量检查统一按上述三份规范执行：业务代码走 src-code 门禁，测试走单元测试门禁，文档走 docs 门禁

三、代码工作规则

3.1 风格一致性

• 所有新增代码必须遵守 code-style
• 所有被改动的旧代码，其新增区域、修改区域和相邻重组代码也必须向 code-style 收敛
• 新增业务逻辑或较大改动，必须先按 code-style 的分层规范判断归属

3.2 改动范围控制

• 小范围修复只调整本次触达区域，不顺手扩大改造范围
• 较大范围改动涉及旧实现迁移时，必须先和需求方确认是否按分层规范重构
• 移除多余功能代码时，以"是否仍被其它业务代码使用"为唯一判断标准；确认未使用即可先移除，不因文档或测试仍存在而阻塞

3.3 UI 组件约束（以 Ant Design 为例）

• 优先使用组件库自带组件，不重复造轮子
• 不得为基础组件额外设置size，统一遵从全局ConfigProvider的尺寸配置
• 默认不得覆盖组件内部样式；优先使用公开的 props、slots、classNames和 token 能力
• 确需调整时，必须先说明能力缺口、原因、影响范围和方案，获得确认后实施；例外代码必须限制作用域并备注原因

3.4 运行时假设

• 明确目标运行环境（如浏览器 Chrome 100+），不对基础对象做过度存在性判断
• 后端接口返回数据按接口定义信任，不做额外兜底堆叠
• 接入后端接口时，必须同步补充同路径 mock；mock 实现不要求单元测试

四、开发流程

4.1 任务启动

1. 方案先行：较大任务、主链路调整、跨模块调整或重构，必须先给出处理方案，确认后再写代码
2. 入口确认：页面/组件/全局能力任务，必须先从对应设计文档（docs/design/pages/、docs/components/、docs/global-design/）定位工作入口；没有入口记录时，先补齐入口文档
3. 边界声明：必须声明本次任务边界；不处理边界外的页面、组件、模型或历史问题

4.2 实现顺序

• 跨公共组件 / 全局能力并影响多页面的任务，先公共能力，再逐个页面消费
• 不在同一轮中混入无关页面治理
• 修改业务代码时，优先保持逻辑靠近使用场景；形成稳定复用关系后才上提到共享目录
• 触达超大文件、超长函数或职责混杂代码时，本次改动不得继续扩大问题；必要时优先抽出局部函数 / 组件 / hook / store / service

4.3 Review 与校验

• 实现完成后进入 review，重点检查：行为回归、测试缺口、规则偏离、文档漂移
• review 范围默认以git diff --name-only与入口文档反推；确需扩大阅读范围时，应说明原因
• code-style 校验、功能测试校验、文档校验拆分处理，按不同校验角色分段完成
• 修复验证问题时只修改当前改动直接涉及的点；其它既有问题只记录到质量待办，不扩大范围

4.4 交付

• 测试全部通过后，必须更新本次改动涉及的业务最终状态文档
• 交付说明默认包含：改动摘要、验证结果、未覆盖风险、必要后续项
• 不复述完整业务背景和已知失败细节

五、单元测试规范（摘要）

完整规则以docs/code-style/unit-tests.md为准

• 代码改动涉及的测试新增、更新、移除和执行，统一按单元测试规范处理
• 除非明确提出，否则不进行浏览器 UI 测试
• 已记录的既有失败，交付时只引用对应记录，不重复展开分析

六、质量跟进（Quality Follow-ups）

项目维护一个docs/quality/目录，专门记录待跟进的质量问题：

• 处理需求时如触达已记录的关联模块，必须先提示对应待落实项
• 触达关联待办后，应同步落实业务逻辑、测试断言和验证结果
• docs/quality仅记录问题和待跟进项，不作为当前需求必须更新的业务文档
• 已落实的最终业务状态，应沉淀到docs/design、docs/global-design或docs/components的对应文档中

七、文档治理

7.1 文档体系

• 项目文档入口：docs/README.md
• 用户手册（如user-manual/）是独立交付目录，默认不纳入业务代码或项目文档的改动范围

7.2 文档规则

• 处理文档时不得保留中间状态或时间线，只保留最终校订时间和最终状态
• 页面、组件和全局能力文档必须能作为工作入口，记录涉及文档、源码目录、参考规范和单元测试入口
• 文档治理任务应独立处理；不把大范围文档入口补齐混入业务功能改动
• 功能代码完成移除后，必须同步处理所有相关文档、入口链接和过期说明
• 业务需求、业务边界和接口资料不得写入项目规则文件，应进入业务文档目录

八、技术基线示例

以下为示例基线，团队按实际情况替换：

九、快速落地 Checklist

首次引入本规范到项目时，按以下清单操作：

• 复制AGENTS.md模板到项目根目录，同步创建CLAUDE.md、GEMINI.md
• 建立docs/code-style/目录，编写src-code/README.md、unit-tests.md、docs.md
• 建立docs/design/、docs/components/、docs/global-design/目录骨架
• 建立docs/quality/目录用于记录质量待办
• 明确技术基线并更新到规范中
• 在团队内宣贯，确保所有使用 AI Agent 的成员知晓并遵守

十、模板使用说明

1. 脱敏替换：将本文中所有项目特定的路径、工具名、技术栈替换为团队实际使用的内容
2. 粒度调整：根据项目规模调整规则粒度。小型项目可精简，大型团队可细化分层
3. 持续迭代：规范不是一成不变的，每季度回顾一次，根据实际协作痛点更新
4. 工具适配：如果使用特定的 Agent 工具（如特定 IDE 插件、CLI），在技术基线章节补充对应约束