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
parent f9a6fe619f
commit c5a8de8cf0
12 changed files with 2922 additions and 35 deletions
@@ -1,50 +1,200 @@
-# [PROJECT_NAME] 项目章程
-<!-- 示例: Spec 章程, TaskFlow 章程等 -->
+<!--
+================================================================================
+同步影响报告 | Constitution Update
+================================================================================
+
+版本变更: 未定义 → 1.0.0 (初始版本)
+
+新增原则:
+  - I. TypeScript 严格模式与类型安全
+  - II. 组件优先架构
+  - III. 测试驱动开发(不可协商)
+  - IV. 性能优先
+  - V. 用户体验一致性
+  - VI. 代码质量与可维护性
+
+新增章节:
+  - 技术标准(技术栈要求、框架版本)
+  - 开发工作流程(代码审查、质量门禁)
+
+模板状态:
+  ✅ plan-template.md - 已验证兼容
+  ✅ spec-template.md - 已验证兼容
+  ✅ tasks-template.md - 已验证兼容
+  ✅ speckit.plan.md - 已更新章程检查引用
+  ✅ speckit.specify.md - 已验证兼容
+
+后续 TODO: 无
+
+================================================================================
+-->
+
+# Agent Park v2 项目章程

 ## 核心原则

-### [PRINCIPLE_1_NAME]
-<!-- 示例: I. 库优先 -->
-[PRINCIPLE_1_DESCRIPTION]
-<!-- 示例: 每个功能都从独立的库开始; 库必须是自包含的、可独立测试的、有文档的; 需要明确的目的 - 不允许仅用于组织的库 -->
+### I. TypeScript 严格模式与类型安全

-### [PRINCIPLE_2_NAME]
-<!-- 示例: II. CLI 接口 -->
-[PRINCIPLE_2_DESCRIPTION]
-<!-- 示例: 每个库都通过 CLI 暴露功能; 文本输入/输出协议: stdin/args → stdout, 错误 → stderr; 支持 JSON + 人类可读格式 -->
+TypeScript 严格模式是强制要求。所有代码必须:

-### [PRINCIPLE_3_NAME]
-<!-- 示例: III. 测试优先(不可协商) -->
-[PRINCIPLE_3_DESCRIPTION]
-<!-- 示例: TDD 强制要求: 编写测试 → 用户批准 → 测试失败 → 然后实现; 严格执行红-绿-重构循环 -->
+- 在 tsconfig.json 中启用 `strict: true` 和所有严格选项
+- 所有函数必须显式声明参数和返回值类型(禁止隐式 any)
+- 禁止使用 `@ts-ignore` 和 `@ts-nocheck`(除非用于临时迁移, 需要工单跟踪)
+- 外部数据必须经过运行时验证(如使用 Zod、Yup 等架构验证库)
+- 所有 API 响应必须定义明确的类型接口

-### [PRINCIPLE_4_NAME]
-<!-- 示例: IV. 集成测试 -->
-[PRINCIPLE_4_DESCRIPTION]
-<!-- 示例: 需要集成测试的重点领域: 新库契约测试、契约变更、服务间通信、共享模式 -->
+**理由**: TypeScript 严格模式在编译时捕获潜在错误, 减少运行时问题, 提高代码可维护性和开发体验。类型安全使重构更安全, 代码更自文档化。

-### [PRINCIPLE_5_NAME]
-<!-- 示例: V. 可观测性, VI. 版本控制和破坏性变更, VII. 简单性 -->
-[PRINCIPLE_5_DESCRIPTION]
-<!-- 示例: 文本 I/O 确保可调试性; 需要结构化日志; 或者: MAJOR.MINOR.BUILD 格式; 或者: 从简单开始, YAGNI 原则 -->
+### II. 组件优先架构

-## [SECTION_2_NAME]
-<!-- 示例: 附加约束、安全要求、性能标准等 -->
+采用 Next.js App Router 架构模式, 遵循以下规则:

-[SECTION_2_CONTENT]
-<!-- 示例: 技术栈要求、合规标准、部署策略等 -->
+- 优先使用 Server Components 而非 Client Components
+- 仅在需要交互性(状态、事件处理、浏览器 API)时使用 'use client' 指令
+- 组件必须保持单一职责和可复用性
+- 布局组件必须使用嵌套布局模式充分利用 Next.js 特性
+- 路由处理程序(Route Handlers)用于 API 端点, 遵循 RESTful 原则
+- 数据获取优先使用 Server Actions 或 Server Components 内的异步函数

-## [SECTION_3_NAME]
-<!-- 示例: 开发工作流程、审查流程、质量门禁等 -->
+**理由**: Server Components 提升性能、减少客户端 JavaScript 体积、改善 SEO。单一职责组件提高可维护性和可测试性。

-[SECTION_3_CONTENT]
-<!-- 示例: 代码审查要求、测试门禁、部署审批流程等 -->
+### 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)

 ## 治理
-<!-- 示例: 章程优先于所有其他实践; 修正需要文档化、批准、迁移计划 -->

-[GOVERNANCE_RULES]
-<!-- 示例: 所有 PR/审查必须验证合规性; 复杂性必须得到证明; 使用 [GUIDANCE_FILE] 进行运行时开发指导 -->
+本章程优先于所有其他实践和规范。

-**版本**: [CONSTITUTION_VERSION] | **批准日期**: [RATIFICATION_DATE] | **最后修正**: [LAST_AMENDED_DATE]
-<!-- 示例: 版本: 2.1.1 | 批准日期: 2025-06-13 | 最后修正: 2025-07-16 -->
+### 修正流程
+
+1. 提出修正: 创建议题描述需要修改的原则及原因
+2. 团队审查: 讨论影响、权衡和替代方案
+3. 批准: 需要多数团队核心成员同意
+4. 文档化: 更新章程版本号和修正日期
+5. 迁移计划: 为破坏性变更提供迁移指南
+
+### 合规审查
+
+- 每个 PR 必须符合章程原则
+- 每次功能规划必须检查章程兼容性
+- 每季度审查章程并更新(如需要)
+- 违反章程需要明确理由和记录(在复杂度跟踪中)
+
+### 版本控制
+
+- **MAJOR**: 向后不兼容的原则删除或重新定义
+- **MINOR**: 新原则添加或实质性扩展
+- **PATCH**: 澄清、措辞、拼写错误修复
+
+**版本**: 1.0.0 | **批准日期**: 2025-12-25 | **最后修正**: 2025-12-25