本文基于一个真实企业级前端项目的协作经验分享如何通过文档驱动的方式规范团队协作、统一代码风格、管理组件体系和保障交付质量。文中已脱敏处理聚焦方法论和实践经验。背景在中大型前端项目中随着团队规模扩大和业务复杂度提升以下问题往往接踵而至代码风格不一致不同开发者写出的代码风格迥异命名、目录组织、分层逻辑各说各话。协作规则口头化约定存在于聊天记录和会议纪要中新人入职无从查阅规则随时间漂移。组件能力不透明公共组件散落各处没有统一的能力说明重复造轮子成为常态。质量标准模糊什么算写完了测试覆盖到什么程度文档更新到哪一步缺乏可执行的门禁。我们尝试用一套文档驱动的协作体系来解决这些问题。以下是核心实践。一、统一协作规则入口三文件同步机制问题不同 AI 工具Claude、Gemini 等和不同开发者需要遵循相同的协作规则但规则散落在各处。方案建立三个等价的规则入口文件内容保持严格一致文件服务对象CLAUDE.mdClaude CodeAGENTS.mdGitHub Copilot / 其他 AgentGEMINI.mdGemini三个文件只维护协作流程、质量门禁和执行约束不重复维护具体代码风格细则。具体风格规范通过引用链接指向专门的规范文档。关键约束修改任一文件时必须同步修改另外两个文件确保所有工具链看到的规则完全一致。实践效果新人入职时阅读任一文件即可了解全部协作规则。AI 辅助编码时所有工具遵循同一套规范输出风格统一。规则变更时有明确的同步责任避免了改了一个忘了一个的问题。二、代码风格规范的分层设计问题一个中型前端项目可能有数十个子目录、数百个文件笼统的代码规范文档往往要么太泛无法执行要么太细难以维护。方案按职责分层拆分规范文档我们将代码风格规范拆分为多个专项文档每个文档聚焦一个职责领域docs/code-style/ ├── README.md# 总入口引用各专项规范├── directories.md# 目录白名单与职责边界├── non-ui-ts.md# 普通 TS 非 UI 代码规范├── api.md# API 请求层规范├── services.md# 业务流程层规范├── stores.md# 状态管理层规范├── models.md# 数据模型规范├── cache.md# 缓存边界规范├── ui.md# UI 公共规范├── components.md# 组件规范├── pages.md# 页面与布局规范├── styles.md# 样式规范└── unit-tests.md# 单元测试规范核心原则1. 业务实现优先靠近使用场景页面专属的组件、hook、常量、类型、样式和工具函数默认放在对应页面目录内。只有当某个能力被多个页面长期稳定复用后才提取到外层公共目录。// ✅ 正确页面专属 hook 放在页面目录内src/pages/incident-ledger/hooks/useLedgerFilters.ts// ❌ 错误尚未形成复用就提前抽象到公共目录src/hooks/useLedgerFilters.ts2. 不为可能复用提前抽象这是一个常见的过度设计陷阱。我们的规则很明确尚未形成复用的代码保留在当前业务上下文中。3. 分层边界清晰业务代码按api → services → stores → hooks → models → constants的职责分层每一层有明确的职责边界层职责禁止事项API请求发送、DTO 转换包含业务流程逻辑Services业务流程编排直接操作 DOM 或 UI 状态Stores状态管理、持久化包含请求逻辑Models数据模型定义、字段口径包含 UI 渲染逻辑Pages页面组合、交互编排承载可复用的业务逻辑实践效果评审时有明确的分层检查标准“请求、流程、状态、模型、渲染是否混在同一文件”新增代码有据可依减少了放哪里都行的主观判断。历史遗留问题可以分阶段治理每次改动让被触达的代码向规范收敛。三、UI 统一规范表单页与列表页问题表单页和列表页是企业级应用最常见的两种页面形态但不同开发者实现的表单页在布局、操作区位置、搜索交互等方面差异很大。方案建立页面级 UI 统一规范约束表单页和列表页的通用组合方案。表单页规范要点独立路由中的创建、编辑、多分区表单固定底部操作区响应式表单分列根据容器宽度自动派生一至四列布局列表页规范要点表格列表 搜索筛选 分页列设置用户自定义显示列页面级列表 store 统一管理状态使用声明机制每个页面的文档开头必须声明采用的是哪种页面规范页面规范表单页统一规范docs/ui-standards/form-page.md这样做的好处是后续调整页面时只需核实该页面声明的规范而不是从头检查所有可能的规范。四、全局能力的文档化管理问题项目中存在大量跨页面共享的全局能力用户认证、HTTP 请求、状态管理、事件桥接等这些能力的实现分散在各处新人难以理解全貌。方案建立全局设计目录为每个全局能力维护独立文档能力文档内容用户与权限当前用户、mock persona、资源权限点、布局层入口权限校验事件桥承接平台事件并转发到应用消息通道运行配置解析运行模式、API 根地址、版本更新检查API 请求请求入口、请求客户端、错误事件通知全局状态local、ui、tag-views、user、reference-data 等 store响应式表单根据容器宽度统一派生分列布局每个全局能力文档必须声明覆盖的源码目录被哪些页面或组件引用参考的代码规范测试入口实践效果处理全局能力时先从索引定位主维护文档再从文档定位源码和测试形成完整的导航链路。全局能力变更时可以通过文档快速定位受影响的页面和组件。五、组件体系的文档化问题公共组件的能力、适用场景和维护重点没有统一记录导致重复开发或误用。方案为每个公共组件维护独立文档记录功能说明组件做什么不做什么适用场景在哪些业务场景下使用代码入口源码目录位置使用边界组件的职责边界和限制测试入口对应的单元测试维护重点需要特别注意的点以一个搜索列表组合组件为例维度内容功能列表页顶部搜索、表头搜索、筛选摘要和列表工具栏组合场景列表页统一搜索交互维护重点草稿/已提交筛选边界、默认筛选重置、表头搜索注入关键约束组件文档只描述当前保留能力组件移除时同步删除文档和入口索引。处理公共组件时先从组件索引定位文档再从文档定位使用页面和测试入口。六、单元测试的分类与门禁问题测试覆盖率 80%是一个常见的口号但实际执行时往往流于形式要么写了大量脆弱的实现细节测试要么遗漏了关键的业务行为断言。方案功能行为测试 vs 静态边界测试我们将单元测试分为两类各有明确的测试对象功能行为测试验证稳定对外能力、状态变化、用户交互、错误结果和用户可观察副作用围绕业务功能点和稳定契约断言不绑定内部实现细节测试名称应让读者看懂业务意图// ✅ 好的测试验证业务行为test(返回空数组当没有匹配的市场时,(){...})test(当 API Key 缺失时抛出错误,(){...})// ❌ 不好的测试绑定实现细节test(调用了 fetchMarketList 函数,(){...})静态边界测试只落实代码风格规范中已明确规定的规则扫描目录、依赖、命名、样式归属和禁止调用规则不得自行增加规范中不存在的限制测试组织__tests__/ ├── boundaries/# 所有 src 改动的固定基线├── api-request/# 通用请求能力├── reference-data/# 引用数据├── incident-domain/# 事件模型├── table-list/# 列表组件├──...# 按功能模块分目录└── helpers/# 共享测试工具不作为执行单元关键规则测试执行的最小单位是功能模块目录不是单个测试文件boundaries/是所有src/改动的固定基线必须执行页面和布局不编写功能行为测试静态边界扫描除外质量门禁流程改动代码 → 自动修复 规范 review → typecheck → lint → 定向测试 → 交付定向测试的范围根据影响链路确定不默认扩大到全量测试。七、文档维护的核心约定1. 只保留最终状态文档不保留中间过程、时间线、旧方案或已不适用功能。功能文档只保留最新有效内容和入口。2. 入口驱动每个目录pages、models、components、global-design都有一个README.md作为入口记录索引和工作入口规则。处理任务时先从入口定位不重新全仓探索。3. 变更同步代码、测试或文档发生变更时必须同步更新相关文档功能代码完成移除后 → 同步处理相关文档、入口链接和过期说明全局能力变更后 → 同步更新被影响的页面和组件文档接口变更后 → 同步更新 mock 和模型文档4. 声明边界任务处理必须声明本次边界。发现边界外既有问题时只记录到质量跟踪目录不扩大本次修改范围。八、与 AI 协作的最佳实践在使用 AI 辅助编码时这套文档体系发挥了额外的价值1. 规则前置将协作规则写入CLAUDE.md等入口文件AI 在每次会话开始时自动加载无需重复说明。2. 文档作为上下文AI 处理任务时先从入口文档定位相关规范和设计文档再开始编码。这比口头描述需求更精确。3. 渐进式收敛AI 生成的代码也需要向规范收敛。我们的规则是新增代码必须严格遵守规范被改动的旧代码新增区域和修改区域也要满足规范历史遗留问题分阶段治理每次改动让代码向规范靠拢4. 边界控制明确告诉 AI 不要做什么比告诉它做什么更重要不处理边界外的页面、组件或模块不顺手扩大改造范围不为未列明的点自行增加测试总结文档驱动的协作体系不是要增加官僚流程而是要让正确的做法成为阻力最小的做法统一入口三个等价文件 引用链接所有工具链看到相同规则。分层规范按职责拆分每个文档聚焦一个领域可独立维护。页面形态标准化表单页和列表页有统一的组合方案。全局能力文档化每个共享能力有独立文档和索引。组件能力透明化每个公共组件有功能、场景和边界说明。测试分类明确功能行为测试 vs 静态边界测试各有清晰的测试对象。变更同步机制代码变更必须同步更新相关文档。这套体系的核心理念是文档不是代码的附属品而是协作的基础设施。当文档足够好用时开发者会主动查阅而不是凭记忆编码当文档成为工作的入口时它就不再是负担而是生产力工具。本文基于实际项目经验整理适用于 React TypeScript Ant Design 技术栈的中大型前端项目。具体规范内容可根据团队实际情况调整。