mzaxd/agent-park
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3869bb23bbfdf25efe342aedb7c8674f5867500b
agent-park/.specify/memory/constitution.md
T
mzaxdandClaude c5a8de8cf0 chore: 初始化 Agent Park v2 项目 
- 更新项目章程，从模板更新为完整版本，包含 TypeScript 严格模式、组件优先架构和 TDD 原则
- 添加项目配置文件（.claude/settings.json、.gitignore、CLAUDE.md）
- 添加完整的 specs 目录，包含需求、契约和文档

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-25 14:21:35 +08:00

7.3 KiB
Raw Blame History

Agent Park v2 项目章程

核心原则

I. TypeScript 严格模式与类型安全

TypeScript 严格模式是强制要求。所有代码必须:

  • 在 tsconfig.json 中启用 strict: true 和所有严格选项
  • 所有函数必须显式声明参数和返回值类型(禁止隐式 any)
  • 禁止使用 @ts-ignore 和 @ts-nocheck(除非用于临时迁移, 需要工单跟踪)
  • 外部数据必须经过运行时验证(如使用 Zod、Yup 等架构验证库)
  • 所有 API 响应必须定义明确的类型接口

理由: TypeScript 严格模式在编译时捕获潜在错误, 减少运行时问题, 提高代码可维护性和开发体验。类型安全使重构更安全, 代码更自文档化。

II. 组件优先架构

采用 Next.js App Router 架构模式, 遵循以下规则:

  • 优先使用 Server Components 而非 Client Components
  • 仅在需要交互性(状态、事件处理、浏览器 API)时使用 'use client' 指令
  • 组件必须保持单一职责和可复用性
  • 布局组件必须使用嵌套布局模式充分利用 Next.js 特性
  • 路由处理程序(Route Handlers)用于 API 端点, 遵循 RESTful 原则
  • 数据获取优先使用 Server Actions 或 Server Components 内的异步函数

理由: Server Components 提升性能、减少客户端 JavaScript 体积、改善 SEO。单一职责组件提高可维护性和可测试性。

III. 测试驱动开发(不可协商)

TDD 是强制要求。测试必须在功能实现之前编写:

  • 红-绿-重构循环必须严格遵循
  • 单元测试覆盖率必须达到 80% 以上
  • 关键业务逻辑必须有集成测试
  • UI 组件必须有可视化测试(如 Playwright 或 Storybook)
  • 所有测试必须在 PR 合并前通过
  • 测试代码质量与生产代码同等重要

理由: TDD 确保代码可测试性、捕获早期错误、作为活文档、提供重构安全网。高测试覆盖率降低生产环境 Bug 风险。

IV. 性能优先

性能是核心质量指标, 必须满足:

  • 首次内容绘制(FCP) < 1.8s
  • 最大内容绘制(LCP) < 2.5s
  • 首次输入延迟(FID) < 100ms
  • 累积布局偏移(CLS) < 0.1
  • 首次字节时间(TTFB) < 800ms
  • 图片必须使用 Next.js Image 组件(自动优化、懒加载)
  • 启用增量静态再生(ISR)或静态生成(SSG)而非服务端渲染(SSR)(如适用)
  • 客户端导航使用 Link 组件
  • 禁止全量导入大型库(如 lodash), 使用按需导入
  • 打包体积: 初始 JavaScript < 200KB gzipped

理由: 性能直接影响用户体验、转化率和 SEO。Google Core Web Vitals 是搜索排名的重要因素。快速加载减少跳出率。

V. 用户体验一致性

跨整个应用必须保持一致的用户体验:

  • 所有页面必须响应式设计(移动优先)
  • 使用统一的设计系统(组件库、颜色、排版、间距)
  • 加载状态必须提供视觉反馈(skeleton、spinner 或进度条)
  • 错误处理必须提供用户友好的消息和恢复操作
  • 表单必须有清晰的标签、验证提示和错误消息
  • 所有交互元素必须有可访问性支持(ARIA 标签、键盘导航)
  • 深色模式支持(如适用)
  • 页面转换必须平滑(使用 View Transitions 或类似技术)

理由: 一致性降低用户学习曲线、提高信任度、改善可访问性。良好的 UX 提高参与度和用户满意度。

VI. 代码质量与可维护性

代码必须遵循最佳实践和编码标准:

  • 使用 ESLint 和 Prettier 进行代码检查和格式化
  • 遵循 Airbnb 或 Standard TypeScript 风格指南
  • 函数复杂度必须控制在合理范围(圈复杂度 < 10)
  • 文件大小限制: < 300 行代码(可读性)
  • 导入路径使用别名(@/components/...)而非相对路径
  • 环境变量使用 .env 文件, 在 .env.example 中记录所有变量
  • 关键功能必须包含 JSDoc 注释
  • 禁止在生产代码中使用 console.log(使用结构化日志库如 Pino)
  • 依赖项必须定期更新(每月审查安全和更新)

理由: 一致的代码风格改善团队协作、降低认知负荷。清晰的代码减少维护成本、加速新开发者上手。

技术标准

技术栈要求

  • 框架: Next.js 14+ (App Router)
  • 语言: TypeScript 5.0+ (严格模式)
  • 样式: Tailwind CSS 或 CSS Modules
  • 状态管理: React Context API 或 Zustand(如需要)
  • 表单: React Hook Form + Zod 验证
  • 数据库: PostgreSQL 或 MongoDB(基于项目需求)
  • ORM: Prisma 或 Mongoose
  • 认证: NextAuth.js 或 Clerk
  • API: RESTful (Route Handlers) 或 tRPC
  • 测试: Vitest/Jest + React Testing Library + Playwright
  • 部署: Vercel(推荐)或 Docker

框架版本控制

  • Next.js 主版本升级需要评估和迁移计划
  • 依赖项版本锁定(使用 package-lock.json 或 yarn.lock)
  • 破坏性变更需要文档和迁移指南

开发工作流程

代码审查要求

所有代码必须经过同行评审:

  • PR 必须包含清晰的描述和链接到相关议题/规范
  • 至少一位团队成员批准才能合并
  • 所有 CI 检查必须通过(测试、类型检查、Lint)
  • PR 大小限制: < 400 行变更(大变更需要拆分)
  • 审查者必须检查: 类型安全、测试覆盖、性能影响、可访问性

质量门禁

代码合并前必须满足:

  • 所有测试通过(单元、集成、E2E)
  • TypeScript 编译无错误
  • ESLint 无警告
  • 性能预算未超限
  • 可访问性检查通过(如 axe-core)
  • 安全扫描无高危漏洞(如 Dependabot)

分支策略

  • main: 生产就绪代码
  • develop: 开发集成分支
  • feature/*: 功能分支(从 develop 分支)
  • fix/*: Bug 修复分支(从 develop 分支)
  • 使用语义化提交消息(Conventional Commits)

治理

本章程优先于所有其他实践和规范。

修正流程

  1. 提出修正: 创建议题描述需要修改的原则及原因
  2. 团队审查: 讨论影响、权衡和替代方案
  3. 批准: 需要多数团队核心成员同意
  4. 文档化: 更新章程版本号和修正日期
  5. 迁移计划: 为破坏性变更提供迁移指南

合规审查

  • 每个 PR 必须符合章程原则
  • 每次功能规划必须检查章程兼容性
  • 每季度审查章程并更新(如需要)
  • 违反章程需要明确理由和记录(在复杂度跟踪中)

版本控制

  • MAJOR: 向后不兼容的原则删除或重新定义
  • MINOR: 新原则添加或实质性扩展
  • PATCH: 澄清、措辞、拼写错误修复

版本: 1.0.0 | 批准日期: 2025-12-25 | 最后修正: 2025-12-25

Reference in New Issue View Git Blame Copy Permalink