OpenCodeInit/docs/README.md

项目文档中心

集中存放架构方案、技术规范、项目约定的文档目录。 Agent 和用户可以随时查阅、创建、更新此目录下的文档。

目录结构

docs/
├── README.md              # 本文件 — 目录标准与使用规范
├── architecture/          # 架构级方案（分层、模块、技术选型、组件架构）
├── conventions/           # 项目约定（编码规范、命名、Git 工作流）
├── specs/                 # 系统级技术规范（API 设计、数据模型、接口协议）
└── reference/             # 参考分析文档（竞品拆解、行业研究、设计参考）

文档命名规范

• 文件名格式：NNN-简短描述.md，NNN 为三位递进编号（从 001 起）
• 示例：001-interaction-design-system.md、002-api-conventions.md
• 编号由 Agent 自动分配（读取目录下最大编号 +1）
• 使用英文短横线命名（kebab-case），描述部分用英文

文档元数据

每个规范文档在文件开头必须包含以下 YAML frontmatter：

---
id: DOC-NNN
title: 文档标题（中文）
type: architecture | convention | spec | reference
status: draft | review | stable | deprecated
created: YYYY-MM-DD
updated: YYYY-MM-DD
related_changelogs: [CL-xxx, CL-xxx]
---

字段说明：

• id：与文件名编号一致
• type：architecture（架构）、convention（规范）、spec（技术规范）、reference（参考分析）
• status：draft（草稿）、review（审查中）、stable（已定稿）、deprecated（已废弃）
• related_changelogs：关联的 changelog 锚点 ID 列表，用于溯因

固化时机（何时写入）

以下情况应创建或更新对应文档：

场景	操作
完成涉及 3+ 模块的架构级改动	创建/更新 architecture 文档
制定或修改了项目公共规范（编码/命名/流程）	创建/更新 conventions 文档
引入或替换了核心依赖（终端引擎/构建工具/UI 库）	更新 architecture 文档
调整了目录结构或模块划分	更新 architecture 文档
设计或修改了 UI/交互标准	创建/更新 architecture 文档
定义了 API 接口、数据模型、通信协议	创建/更新 specs 文档
完成了竞品分析、行业调研、设计参考的深度研究	创建/更新 reference 文档
约定被废弃或替换	标记为 deprecated，写明替代文档编号

更新与维护

• 关联 changelog：每次基于开发改动更新文档时，必须在 related_changelogs 中追加对应的 CL-xxx 锚点 ID
• 代理审查：Agent 在周期审查中会自动对比 changelog 与文档的一致性（见 spec-docs Skill）
• 手动审查：用户可在任意时间要求 Agent 执行文档审查
• 冲突处理：当文档与代码/changelog 存在逻辑互斥时，Agent 应标记为 review 状态并提请用户裁决

与其它系统的关系

系统	关系	说明
dev-changelog	上游数据源	changelog 记录"做了什么"，docs 沉淀"如何做的规范"
spec-docs Skill	管理工具	负责文档的创建提醒、周期审查、一致性校验
deferred-decisions	互补	deferred 记录"暂不做的方案"，docs 记录"已确定的方案"
profile-memory	互补	profile 描述项目"是什么"，docs 描述项目"怎么做"