# code996 项目协作规则

## 核心理念

这是 code996 项目的核心协作规则文档。code996 是一个基于 Node.js 的本地分析工具，通过分析 Git commit 的时间分布来计算项目的“996 指数”，并以本地 Web、终端、JSON 或 Markdown 展示结果。所有开发活动必须以此为基准，与 AI 开发伙伴的协作必须严格遵循这些规则。

## 文档体系结构

### 事实基线 (State) 文档

这些文档描述项目**"现在是什么样子"**，是所有工作的出发点和事实依据：

- **[项目路线图](projectRoadmap.md)** - 项目的整体规划和未来方向
- **[技术栈文档](techStack.md)** - 技术选型、关键库及配置说明
- **[代码库概览](codebaseSummary.md)** - 项目的目录结构、核心模块和架构概述
- **[本地 Web 报告](features/web-report.md)** - Web 报告的数据契约、生成方式、安全边界和降级策略
- **[官方站点](features/public-website.md)** - 官网源码、历史路由兼容与 GitHub Pages 部署边界

### 规则与流程 (Rules & Process) 文档

这些文档定义我们**"要怎么做"**，并记录行动的过程：

- **[项目规则](./README.md)** - 开发协作的核心规则（本文档）
- **[任务中心](./tasks/)** - 所有已完成或进行中的持久化任务档案

## 核心协作原则

### 1. 用户意图至上 (User Intent First)

- 用户的明确指令拥有最高优先级
- 所有规则和流程都是为了更好地服务于用户目标
- 如果用户指令与已存在的文档或代码不同，优先服从用户指令
- 执行后可简要提醒可能的技术债务

### 2. 依据驱动 (Evidence-Driven)

- 所有重要建议必须基于事实和清晰的定义
- 特别是`.docs`中的事实作为**基线**
- 行动必须以已知的**基线**为起点
- 避免基于假设的决策

### 3. 状态外化 (Stateful Execution)

- 对于任何非平凡任务，将思考过程和行动计划完全书面化
- 使其可见、可追溯、可协同

### 4. 验证确认 (Verification by User)

- 所有代码变更的默认验证方式为**用户手动测试**
- 只需提供清晰的验证步骤

### 5. 主动思考与学习 (Proactive Thinking & Learning)

- 需要**主动思考**，发现潜在问题和优化点
- 任务完成后，通过**闭环学习**将经验沉淀
- 主动提议更新项目规则

### 6. 情景感知与务实 (Context-Aware & Pragmatic)

- 必须能**感知情景**，区分任务的规模和意图
- 采用最高效的流程，避免对微小任务进行不必要的过度规划
- 务实解决问题

### 特别要求

- 根据不同的Git仓库规模和分析需求选择合适的算法复杂度
- 关注Git分析算法的准确性、性能优化和用户体验改进
- 为复杂的数据分析算法添加详细的注释和文档说明
- 验证步骤应包含具体的命令行测试用例
- 始终优先考虑终端用户体验，确保命令参数直观、输出信息清晰
- 基于实际的Git数据结构和命令行最佳实践进行设计

## 技术标准与约定

### 设计标准

- **输出方式**: 默认输出终端报告并保存本地 Web；交互终端随后询问是否打开且默认选择“打开本次报告”，`--open` / `--no-open` 可覆盖；另支持 JSON 与 Markdown
- **设计语言**: 延续 code996 的像素终端视觉，重点突出 996 指数和 24 小时提交脉冲
- **布局原则**: Web 响应式适配桌面和移动端；终端表格继续自适应宽度
- **输出格式**: Vue Web 报告、自适应终端表格、JSON、Markdown
- **兼容性**: 支持 Windows、macOS、Linux 等主流操作系统

### 开发标准

- **核心框架**: Commander.js（命令行界面）
- **Web 框架**: Vue 3 + Vite + chart.xkcd
- **编程语言**: TypeScript（严格模式）
- **终端美化**: Chalk（彩色输出）
- **进度指示**: Ora（加载动画）
- **表格输出**: cli-table3（数据表格展示）
- **构建工具**: TypeScript Compiler（CLI）+ Vite（Web）
- **包管理**: npm / pnpm 双锁文件；发布 CI 以 npm 为准

### 代码质量

- **类型安全**: 严格的 TypeScript 类型检查，完整的类型定义
- **代码风格**: Prettier 统一格式化（单引号、120字符行宽、ES5尾逗号）
- **命名规范**: 语义化命名，避免缩写，使用驼峰命名法
- **注释要求**: 复杂算法和业务逻辑必须添加清晰注释
- **测试要求**: Jest 覆盖 CLI 与输出层，Vitest 覆盖 Web 组件和双语状态

## 质量保证

- 完成任务后必须进行**交付前自检**
- 检查代码-文档一致性

### 代码质量检查

- [ ] TypeScript 类型检查通过（`npx tsc --noEmit`）
- [ ] Prettier 代码格式化检查（`npx prettier --check src/`）
- [ ] Jest 单元测试通过（`npm test`）
- [ ] Web 类型检查和生产构建通过（`npm run build:web`）
- [ ] 官方站点类型检查和生产构建通过（`npm run build:website`）
- [ ] 桌面与移动端无页面级横向溢出，语言切换后标签同步更新
- [ ] CLI 命令功能正常（手动测试各种参数组合）
- [ ] 输出格式正确（表格对齐、颜色显示、自适应宽度）
- [ ] 跨平台兼容性（Windows、macOS、Linux 基本功能测试）
- [ ] Git 数据采集准确（不同仓库类型测试）

### 文档质量检查

- [ ] 与代码实现一致
- [ ] 信息完整准确
- [ ] 使用示例可执行验证
- [ ] 链接有效可访问

## 错误处理与改进

### 自我纠错机制

- 发现违反规则时，立即停止并承认错误
- 指出违反的具体规则
- 重新按正确流程生成回答

### 持续改进

- 定期审查和更新规则
- 记录最佳实践和经验教训
- 优化开发流程和工具链