DEVELOPMENT_GUIDE.md

开发流程与协作指南

本文档记录 xyjson 项目的开发流程规范，特别是与 AI 协作的工作方式。

文档管理

任务管理文档

• task_todo.md - 原始需求记录（用户维护）

  • 需求ID格式：TODO:YYYY-MM-DD/n
  • 用户记录开发想法和需求
  • AI 不允许修改此文档内容，只能在 TODO 下添加 DONE 子标题

• task_log.md - 任务完成日志（AI 维护）

  • 任务ID格式：YYYYMMDD-HHMMSS
  • AI 完成任务后记录工作日志

协作流程

1. 用户在 task_todo.md 中记录需求（带需求ID）
2. 给 AI 的提示词中包含需求ID
3. AI 分析需求并实施
4. AI 完成任务后在 task_log.md 记录日志
5. 同时在 task_todo.md 的对应 TODO 下添加 ### DONE:任务ID
6. 提交 git，提交消息包含需求ID

Git 提交规范

提交消息格式

<type>(scope): 简短描述

详细描述（可选）

消息要素

• type: feat, fix, docs, refactor, style, perf, test, chore
• scope:
  • 如果有需求ID，使用格式 YYYY-MM-DD/n
  • 如果无需求ID，留空或使用英文单词
• 描述语言: 前缀用英文，描述和正文用中文

示例

feat(2025-10-13/1): 实现文档读写方法内联化

将 Document 类的 read/write 方法从 cpp 文件迁移到头文件中，
支持完全 head-only 库架构。

代码规范

注释规范

• 代码注释: 使用英文，以简约为主
• 文档注释: 使用中文，详细描述功能
• 函数注释: 相关重载函数按组统一注释，不需为每个函数单独注释

特殊情况处理

• 无预记录需求: 完成后仍记录日志，提交时 scope 留空
• 人工微调: 用户后续调整时，提交 scope 可留空

开发原则

主提交与辅提交

• 主提交: 带需求ID的提交，完成主要功能
• 辅提交: 无需求ID的提交，用于微调和补充

文档完整性

• 重要功能变更必须在相关文档中记录
• AI 完成工作后需确保文档同步更新

此指南应与 AGENTS.md 配合使用，AGENTS.md 关注技术实现，本文档关注流程规范。