Vibe Coding + TDD：用一份 CLAUDE.md 让 AI 全自动走完测试驱动开发

use thiserror::Error;
 
#[derive(Debug, Error, PartialEq, Eq)]
pub enum RateLimiterError {
    #[error("no tokens available, retry after {retry_after_ms}ms")]
    NoTokensAvailable { retry_after_ms: u64 },
}

mod error;
pub use error::RateLimiterError;
 
pub struct TokenBucket {
    capacity: u32,
    refill_rate: f64,
    available: f64,
    last_refill: std::time::Instant,
}
 
impl TokenBucket {
    pub fn new(capacity: u32, refill_rate: f64) -> Self {
        todo!()
    }
 
    pub fn try_acquire(&mut self) -> Result<(), RateLimiterError> {
        todo!()
    }
 
    pub fn available_tokens(&mut self) -> u32 {
        todo!()
    }
 
    fn refill(&mut self) {
        todo!()
    }
}
 
#[cfg(test)]
mod tests {
    use super::*;
 
    #[test]
    fn test_new_bucket_starts_full() { /* ... */ }
 
    #[test]
    fn test_try_acquire_success() { /* ... */ }
 
    #[test]
    fn test_try_acquire_rejects_when_empty() { /* ... */ }
 
    #[test]
    fn test_refill_over_time() { /* ... */ }
 
    // ... 更多测试
}

impl TokenBucket {
    pub fn new(capacity: u32, refill_rate: f64) -> Self {
        Self {
            capacity,
            refill_rate,
            available: capacity as f64,
            last_refill: std::time::Instant::now(),
        }
    }
 
    pub fn try_acquire(&mut self) -> Result<(), RateLimiterError> {
        self.refill();
        if self.available >= 1.0 {
            self.available -= 1.0;
            Ok(())
        } else {
            let retry_after_ms = ((1.0 - self.available) / self.refill_rate * 1000.0).ceil() as u64;
            Err(RateLimiterError::NoTokensAvailable { retry_after_ms })
        }
    }
 
    pub fn available_tokens(&mut self) -> u32 {
        self.refill();
        self.available.floor() as u32
    }
 
    fn refill(&mut self) {
        let now = std::time::Instant::now();
        let elapsed = now.duration_since(self.last_refill).as_secs_f64();
        self.available = (self.available + elapsed * self.refill_rate).min(self.capacity as f64);
        self.last_refill = now;
    }
}

# 项目名称
 
## 开发流程
 
本项目严格遵循 TDD（测试驱动开发）流程：
 
1. **先写测试，再写实现** — 不允许出现 `todo!()` 占位的实现
2. **测试必须先跑失败** — 确认测试在检验真实行为
3. **最小实现让测试通过** — 不要过度设计
4. **重构时测试必须全绿** — 改完代码第一件事跑 `cargo test`
 
## 代码规范
 
- **错误处理**：禁止 `.unwrap()` 和 `.expect()`（测试代码除外）
  - 库代码用 `thiserror` 定义错误类型
  - 应用代码用 `anyhow` 传播错误
  - 每个 `?` 都要考虑调用者需要什么上下文
- **数据模型**：优先用 enum 而不是 String 表示有限集合
- **命名**：测试函数用英文 snake_case，注释用中文说明"为什么测这个"
- **并发**：共享状态用 `Arc<Mutex<T>>` 或 `Arc<RwLock<T>>`，禁止 `Rc`
 
## 测试规范
 
- 单元测试放在 `#[cfg(test)] mod tests` 里
- 集成测试放在 `tests/` 目录下
- 测试命名格式：`test_<场景>_<期望行为>`
- 每个公开函数至少覆盖：正常路径、错误路径、边界条件
- 涉及数据变换的模块必须有 proptest roundtrip 测试
 
## 依赖选择
 
- 解析：`nom`（不用正则）
- 错误：`thiserror`（库）/ `anyhow`（应用）
- 序列化：`serde` + `serde_json`
- 测试：`proptest`（property-based）、`tempfile`（临时文件）
- 日志：`tracing`（不用 `println!`）
 
## 项目结构
 
src/
├── lib.rs          # 库入口
├── error.rs        # 错误类型定义
├── types.rs        # 核心数据模型
tests/              # 集成测试
fixtures/           # 测试数据

## Web 服务规范
 
- 框架：axum（不用 actix-web）
- 状态管理：`State<Arc<AppState>>`，禁止在 state 里用 `Rc`
- 中间件：错误处理用 `tower::ServiceBuilder`，不用手写
- 数据库：`sqlx`（编译期检查 SQL），不用 `diesel`

## CLI 规范
 
- 参数解析：`clap` derive 模式
- 输出：结构化日志用 `tracing`，用户可见输出用 `eprintln!`（错误）/ `println!`（正常）
- 退出码：0 成功，1 用户错误，2 系统错误

## 代码审查
 
提交前检查：
- [ ] `cargo test` 全绿
- [ ] `cargo clippy` 无警告
- [ ] 没有新增 `.unwrap()`（测试除外）
- [ ] 新增的公开函数有测试覆盖
- [ ] 错误类型用 `thiserror` 定义，不是 `String`

## 禁止的写法
 
- ❌ `.unwrap()` 在非测试代码中
- ❌ `String` 当错误类型
- ❌ `println!` 做日志（用 `tracing`）
- ❌ `clone()` 来绕过借用检查（先想清楚所有权）
- ❌ `unsafe` 除非有注释说明为什么安全

# 项目名称
 
## 开发流程
 
1. 先写测试，再写实现
2. 禁止 `.unwrap()`（测试除外）
3. 错误类型用 `thiserror`
4. 每个公开函数至少覆盖：正常路径、错误路径、边界条件