<!--
同步影响报告 (Sync Impact Report)
=======================================
版本变更: [初始版本] → 1.0.0
修改的核心原则:
  - I. Rust 2024 标准 (新增)
  - II. 中文文档强制要求 (新增)
  - III. 测试驱动开发 (新增)
  - IV. 集成测试强制要求 (新增)
  - V. 安全优先 (新增)
  - VI. 向后兼容性 (新增)

新增章节:
  - 开发规范（技术栈要求、文档规范、Git 提交规范）
  - 质量保障（代码审查清单、发布流程）

模板更新状态:
  ✅ constitution.md - 已更新 (本文件)
  ✅ plan-template.md - 已更新（中文化 + Rust 2024 配置）
  ✅ spec-template.md - 已更新（中文化）
  ✅ tasks-template.md - 已更新（中文化 + 集成测试强化）

后续 TODO:
  - 无待办事项，所有模板已同步完成
-->

# AgentSwitch 项目宪章

## 核心原则

### I. Rust 2024 标准 (NON-NEGOTIABLE)

**强制要求**:
- 项目必须使用 Rust 最新稳定版本
- 严格遵循 `edition = "2024"` 标准规范
- 所有代码必须通过 `cargo clippy` 检查，无警告
- 遵循 Rust 官方代码风格指南（通过 `rustfmt` 格式化）
- 使用现代 Rust 语法特性，避免过时模式

**理由**: Rust 2024 Edition 提供最新的语言特性和编译器优化，确保代码的长期可维护性和性能表现。

### II. 中文文档强制要求 (NON-NEGOTIABLE)

**强制要求**:
- 所有规范文档（spec.md）必须使用中文编写
- 所有任务文档（tasks.md）必须使用中文编写
- 设计文档、架构文档必须使用中文编写
- 代码注释必须使用中文
- 允许使用英文的场景：
  - 代码本身（变量名、函数名、类型名）
  - 关键技术术语（如 HTTP, API, JSON, TOML）
  - 命令行参数和标志
  - 第三方 API 引用

**理由**: 中文作为团队主要工作语言，确保所有团队成员能够准确理解需求和设计意图，减少沟通成本。

### III. 测试驱动开发

**强制要求**:
- 新功能开发必须遵循 TDD 流程：编写测试 → 用户确认 → 测试失败 → 实现功能
- 单元测试覆盖率不得低于 80%
- 每个公开的 API 必须有对应的测试用例
- 遵循 Red-Green-Refactor 循环

**理由**: TDD 确保代码质量，提前发现设计问题，为重构提供安全网。

### IV. 集成测试强制要求 (NON-NEGOTIABLE)

**强制要求**:
- 每个功能完成后必须执行完整的集成测试
- 集成测试必须覆盖：
  - 配置文件读写完整流程
  - Agent 工具适配器（backup/apply/restore）
  - 命令行交互的端到端场景
  - 错误处理和边界条件
- 集成测试失败时禁止合并代码
- 测试结果必须文档化（记录在 spec.md 的测试章节）

**理由**: 集成测试确保各个模块协同工作，防止因配置问题导致的运行时故障，这对配置管理工具至关重要。

### V. 安全优先

**强制要求**:
- API Key 必须加密存储（使用操作系统密钥链或加密文件）
- 配置文件权限必须设置为用户仅读（600）
- 不得在日志中输出敏感信息
- 备份文件中的 API Key 必须脱敏或加密

**理由**: 配置管理工具涉及大量 API 密钥，安全性是核心关切。

### VI. 向后兼容性

**强制要求**:
- 配置文件格式变更时必须提供迁移脚本
- 不得破坏现有用户的配置文件
- 重大变更必须在版本号中体现（遵循语义化版本）

**理由**: 用户配置数据至关重要，破坏性变更会导致用户体验灾难。

## 开发规范

### 技术栈要求

**Rust 生态系统**:
- CLI 框架: `clap` 4.x (derive 特性)
- 序列化: `serde` + `serde_json` + `toml`
- 错误处理: `anyhow`
- 路径操作: `dirs` (跨平台路径)
- 测试: 内置 `cargo test` + 集成测试框架

**代码质量工具**:
- `cargo fmt` - 代码格式化
- `cargo clippy` - Lint 检查
- `cargo audit` - 安全漏洞检查

### 文档规范

**中文文档要求细节**:
1. **spec.md** - 功能规格说明
   - 必须使用中文描述功能需求
   - 代码示例注释使用中文
   - API 说明使用中文

2. **tasks.md** - 任务分解
   - 任务描述使用中文
   - 验收标准使用中文
   - 技术细节说明使用中文

3. **代码注释**:
   ```rust
   /// 将指定的模型配置应用到目标 Agent 工具
   ///
   /// # 参数
   /// - `model_config`: 模型配置信息
   ///
   /// # 返回
   /// - `Ok(())`: 应用成功
   /// - `Err(...)`: 应用失败及错误原因
   fn apply(&self, model_config: &ModelConfig) -> anyhow::Result<()> {
       // 实现细节...
   }
   ```

### Git 提交规范

**提交信息格式** (Conventional Commits 中文版):
```
<类型>: <简短描述>

<详细说明>
```

**类型**:
- `feat`: 新功能
- `fix`: Bug 修复
- `refactor`: 重构
- `test`: 测试相关
- `docs`: 文档更新
- `chore`: 构建/工具链相关

**示例**:
```
feat: 添加 Claude Code 适配器支持

实现了 Claude Code 的配置文件检测和修改功能,
支持自动备份和恢复操作。
```

## 质量保障

### 代码审查清单

- [ ] 代码通过 `cargo clippy` 无警告
- [ ] 代码通过 `cargo fmt` 格式化
- [ ] 单元测试覆盖率 ≥ 80%
- [ ] 集成测试全部通过
- [ ] 文档已更新（中文）
- [ ] API Key 安全处理已验证
- [ ] 配置文件兼容性已测试

### 发布流程

1. 所有测试通过（单元 + 集成）
2. 代码审查通过
3. 文档完整（中文 spec 和 tasks）
4. 更新 CHANGELOG.md
5. 创建 Git Tag
6. 发布到 GitHub Releases

## 治理规则

### 宪章修订流程

1. 提出修订建议（说明理由和影响）
2. 团队评审和讨论
3. 更新宪章版本号（遵循语义化版本）
4. 同步更新所有相关模板
5. 通知所有成员

### 版本策略

- **MAJOR**: 移除或重定义核心原则（破坏性变更）
- **MINOR**: 新增原则或重大补充
- **PATCH**: 文案优化、错别字修正

### 合规性检查

所有 Pull Request 必须验证：
- Rust 2024 Edition 规范
- 中文文档要求
- 测试覆盖率要求
- 安全性要求

复杂度必须合理说明，避免过度设计。

---

**版本**: 1.0.0 | **批准日期**: 2026-02-27 | **最后修订**: 2026-02-27
