# CLAUDE.md

## 项目概况
这是 [项目名]，一个 [一句话描述]。
技术栈：[语言/框架/数据库]

## 编码规范
- 使用 [语言] [版本]
- 遵循 [代码风格指南]
- [2-3 条最关键的项目规范]

## 重要约束
- ❌ 禁止：[列出绝对不能做的操作]
- ⚠️ 注意：[列出需要特别小心的事项]

# CLAUDE.md — 后端 API 项目

## 项目概况
这是一个基于 Django REST Framework 的 SaaS 后端，
为「AI创业内参」公众号提供内容管理和发布 API。
数据库：PostgreSQL 15，缓存：Redis 7。

## 技术约束
- Python 3.11，类型注解必须完整（mypy strict 模式）
- Django 4.2 LTS，不要用 5.x 的新特性
- ORM 只用 Django ORM，禁止手写原生 SQL（除 migrations）
- API 返回统一使用 `{ "code": 0, "data": ..., "message": "" }` 格式
- 所有 API 端点必须有 `permission_classes`

## 编码风格
- 模型字段必须写 `help_text`
- View 层逻辑不超过 20 行，复杂逻辑抽到 services.py
- 用 `select_related` / `prefetch_related` 优化 N+1 查询
- 异常处理：业务异常抛 `BusinessException`，不要裸抛 `Exception`

## 禁止操作
- ❌ 不要修改 `settings/production.py`（生产配置）
- ❌ 不要直接操作生产数据库（只用 Django ORM + migrations）
- ❌ 不要引入新的第三方依赖（需先讨论）
- ❌ 不要在 migrations 中写数据迁移逻辑（用 management commands）

## 测试要求
- 每个 service 函数必须有单元测试（pytest）
- API 端点必须有集成测试（APITestCase）
- 测试覆盖率不低于 80%

## 常见陷阱
- `datetime.now()` 不是 timezone-aware，用 `timezone.now()`
- DRF Serializer 中 `update()` 必须处理 partial update
- Redis key 命名：`{项目前缀}:{模块}:{标识}`

# CLAUDE.md — 前端管理后台

## 项目概况
React 18 + TypeScript 管理后台，用于内容编辑和数据分析。
状态管理：Zustand，UI：Ant Design 5，构建：Vite。

## 技术约束
- TypeScript strict 模式，禁止 `any`（除非有注释说明原因）
- React 函数组件 + Hooks，不用 Class 组件
- 样式统一用 Ant Design 的 `token` 系统 + CSS Modules
- API 调用统一走 `@/services/api.ts` 封装的 `request` 函数

## 组件规范
- 组件文件结构：
  ```
  ComponentName/
  ├── index.tsx        # 主组件
  ├── ComponentName.module.css  # 样式
  ├── types.ts         # 类型定义
  └── __tests__/       # 测试
  ```
- 用 `React.memo` 包裹纯展示组件
- 表单统一用 Ant Design `Form` + 自定义 `useForm` hook

## 禁止操作
- ❌ 不要直接在组件中调 API（走 services 层）
- ❌ 不要手动操作 DOM（除非万不得已）
- ❌ 不要引入 moment.js（用 dayjs，已在项目中）
- ❌ 不要修改 `vite.config.ts`（构建配置）

## 常见陷阱
- `useEffect` 依赖数组不要遗漏（开启 `react-hooks/exhaustive-deps` 规则）
- Zustand store 不要在组件外直接修改（用 `setState`）
- Ant Design Table 的 `rowKey` 必须唯一

# CLAUDE.md — AI 内容工厂项目

## 项目概况
基于 Hermes Agent 的 AI 内容创作流水线，通过多个子 Agent
（research → outline → write → review → publish）协作产出公众号文章。
总代码量约 8,000 行 Python，200+ 篇已发布文章。

## 架构约束
- 子 Agent 通过 `delegate_task` 调用，输出通过 Markdown 文件传递
- 配置文件在 `~/.hermes/projects/ai-neican/`
- 文章质量评分用 `rate_article()` 函数，≥60 分才进入下一步

## Skill 开发规范
- Skill 文件用 YAML front matter + Markdown 正文
- 每个 Skill 必须包含：`name`、`description`、`triggers`
- 工具类 Skill 必须给出「可直接复制的配置/代码片段」
- 引用数据必须附来源 URL

## 发布规范
- WeChat 草稿箱 HTML：不包含 `<h1>` 标题，图片用 mmbiz CDN URL
- 网站 HTML：必须包含 `<h1>` 标题，图片用本地 `/images/` 路径
- 封面图：1792×1024 PNG，文字用 canvas 叠加而非直出
- 插图：每篇 3-5 张，必须含中文数据标注

## 禁止操作
- ❌ 不要覆盖 `content/outputs/01-article.md`（等 reviewer 审批后）
- ❌ 不要在 Skill 中硬编码 API Key（用环境变量）
- ❌ 不要删除历史草稿（`content/draft-*`）
- ❌ 不要直接操作生产 WeChat API（先走草稿箱验证）

## 常见陷阱
- `wc -w` 不能正确统计中文字数，用 `wc -c` 或 Python regex
- WeChat `access_token` 必须用 `stable_token` 接口（普通接口返回 40001）
- 封面图文件名不能含中文（微信 API 返回 41005）
- `delegate_task` 超时不等于失败——先检查输出文件是否完整

# CLAUDE.md — 用户行为分析项目

## 项目概况
通过 ClickHouse 中的用户行为日志，分析公众号读者的阅读习惯、
分享行为和付费转化路径。输出周报和策略建议。

## 技术约束
- Python 3.11 + Jupyter Lab
- 数据库查询用 `clickhouse-driver`，不要用 SQLAlchemy
- 可视化：Plotly（交互式图表）+ Matplotlib（静态导出）
- 数据输出：Pandas DataFrame → Parquet 文件

## 分析规范
- 所有分析从 `notebooks/` 目录启动
- 原始数据不修改，所有转换保存为新文件
- SQL 查询放在 `sql/` 目录，不要在 Python 中拼接 SQL
- 每个分析结论必须附带置信区间或 p 值

## 禁止操作
- ❌ 不要在 ClickHouse 上执行 `SELECT *`（数据量太大）
- ❌ 不要在生产数据库上直接跑分析（用只读副本）
- ❌ 不要修改历史数据表

## 常见陷阱
- ClickHouse 的 `JOIN` 语义与 MySQL 不同（默认是 `ANY` 而非 `ALL`）
- 时间字段注意时区：ClickHouse 存 UTC，分析时转 Asia/Shanghai
- Pandas `merge` 默认是 inner join，确认是否需要 outer

不要这样写：
  result = User.objects.filter(status=1).all()
应该这样写：
  result = User.objects.filter(status=User.Status.ACTIVE).select_related('profile')

## 🤔 每次修改前请自问
1. 这个改动会影响现有功能吗？如果是，哪些测试需要更新？
2. 有更简单的实现方式吗？（先想最简单的方案，再考虑要不要复杂化）
3. 改动是否符合上面的技术约束和禁止清单？

{
  "autoCompact": true,
  "tokenBudget": 32000,
  "permissions": {
    "allow": ["Bash(claude:*)", "Read(*)"],
    "deny": ["Bash(curl:*)", "WebSearch"]
  }
}