dev-docs-standards

规定开发项目的文档体系：明确 README、AGENTS、契约、参考、CHANGELOG、看板与 WIP、MEMORY 各文件/模块的用途、内容格式、维护责任人及防腐化机制。用于指导新建或接管项目时合理组织文档，判断特定内容应归属哪份文件，整理 docs 目录结构，撰写 README / AGENTS / CHANGELOG，配置文档门禁（如 CI 校验），或识别 agent 记忆中堆积了本应写入正式文档的信息。 - **README**：项目总览，面向新成员和外部使用者。包含项目名称、一句话简介、快速开始指南（安装/运行/测试）、核心功能、技术栈、贡献方式、许可证等。由项目负责人或核心维护者定期更新，确保与代码同步；可通过 CI 检查关键命令是否可执行来防腐化。 - **AGENTS**：定义项目中各类智能体（如 AI Agent、自动化脚本、微服务等）的职责、行为规则、接口约定、生命周期及协作流程。采用结构化格式（如 YAML/JSON Schema 或 Markdown 表格），由架构师或 Agent 负责人维护，变更需通过设计评审并同步更新契约。 - **契约（Contracts）**：明确定义模块/服务间的接口规范，包括 API 协议（OpenAPI/Swagger）、消息格式（Protobuf/Avro）、数据 schema、错误码、SLA 等。以机器可读格式存储，由接口所有者维护，集成到 CI/CD 中进行契约测试，防止实现偏离约定。 - **参考（Reference）**：技术细节手册，如内部 API 文档、配置项说明、算法原理、数据库设计、部署拓扑等。按主题分章节，由对应模块开发者编写，技术负责人审核，结合自动化工具（如 Swagger UI、Javadoc）生成并保持同步。 - **CHANGELOG**：按版本记录所有用户可见的变更，遵循语义化版本和 Keep a Changelog 规范。区分 Added/Changed/Deprecated/Removed/Fixed/Security 类别，由发布经理在每次发版时更新，禁止手动修改历史条目，确保可追溯。 - **看板与 WIP（Work In Progress）**：可视化任务状态（如 GitHub Projects、Jira Board），明确当前迭代目标、进行中的任务、阻塞项及责任人。由 Scrum Master 或项目经理每日维护，WIP 限制防止过度并行，状态变更需及时同步至相关文档。 - **MEMORY**：临时性、上下文相关的信息缓存，如会议纪要、临时决策、调试日志、Agent 对话历史等。仅限短期留存，明确标注“非持久化”，由创建者负责定期清理；若信息具备长期价值，必须迁移至上述正式文档中，避免知识流失。 **防腐化机制**：每份文档指定唯一 Owner；重大变更需 PR 审查；CI 集成文档校验（如链接有效性、示例可运行性）；定期审计（如季度文档健康检查）；鼓励“文档即代码”实践，将文档纳入版本控制与自动化流水线。

存档时间线

版本索引永久保留；内容副本只保留最新 1 份，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本