AI 辅助开发

使用 AI 工具高效参与项目开发

CLAUDE.md 和 AGENTS.md

项目根目录包含 AI 助手的指导文件：

• CLAUDE.md / AGENTS.md — AI 编码助手的项目上下文文件（AGENTS.md 是 CLAUDE.md 的软链接）

  • 项目结构和架构原则
  • 常用开发命令（dev、build、test、database）
  • 开发工作流程（包括 OpenSpec 集成）
  • Git 提交规范和分支策略
  • Package 开发指南
  • 数据库工作流程
  • 故障排查提示

• openspec/AGENTS.md — OpenSpec 工作流说明，用于规范化的功能规划

AI 助手（如 Claude Code、Cursor、GitHub Copilot）在读取这些文件后，能更准确地理解项目约定并生成符合规范的代码。

更新 CLAUDE.md 的时机

当确定新的代码规范时，需要同步更新：

1. CLAUDE.md — 更新 AI 助手的指导内容
2. apps/mono-web/content/docs/ — 更新对应的开发文档（如本文档、coding-standards.zh.mdx 等）
3. 相关 package README.md — 如果变更影响包级能力、API 或使用方式，也要同步更新参考文档

文档分层策略

本项目采用 AI-first 的文档策略，文档按用途分为两层：

1. Package README.md（AI + 开发者）

每个 packages/xxx/README.md 包含该包的技术细节：

• API Reference 和类型签名
• 使用示例和代码片段
• 配置选项和环境变量
• 内部架构和设计决策

AI 在开发时会自动读取对应包的 README.md，无需手动指定。这是 AI 理解和使用包的首要参考。

2. Fumadocs 网站文档（面向用户）

apps/mono-web/content/docs/packages/ 下的 .mdx 文件是面向模板使用者的教程文档：

• 功能介绍和使用场景
• 快速上手指南
• 最佳实践和注意事项
• 与其他包的集成示例

维护原则

• README.md 是 source of truth — 技术细节以 README.md 为准
• 不需要维护两套相同内容 — Fumadocs 文档侧重「教程」，README.md 侧重「参考」
• 新增或修改包时，优先更新 packages/xxx/README.md，网站文档按需更新

推荐 AI 编码工具

• Claude Code — Anthropic 官方 CLI，支持 plan mode 和自动化开发
• Cursor — AI-first 代码编辑器
• GitHub Copilot — VS Code / JetBrains 插件

OpenSpec 工作流

对于较大的功能开发，项目使用 OpenSpec 工作流进行规范化规划：

三阶段流程

1. Creating（创建提案）

   • 在 openspec/changes/ 下创建 .md 提案文件
   • 描述功能目标、技术方案、影响范围
   • 使用 /openspec:proposal 命令辅助生成

2. Implementing（实施）

   • 根据提案进行开发
   • 使用 /openspec:apply 命令执行变更

3. Archiving（归档）

   • 完成后归档提案
   • 使用 /openspec:archive 命令归档

适用场景

• 涉及多个模块的大功能
• 架构变更或重构
• 需要团队讨论的技术决策

Claude Code Plan Mode

对于较小的任务，可以直接使用 Claude Code 的 plan mode：

1. 描述任务需求
2. Claude Code 分析代码库并生成实施计划
3. 确认计划后自动执行

适合：Bug 修复、小功能添加、文档更新、代码重构等。