团队协作文档规范框架搭建 #1

mubaihe349 · 2026-08-04T11:54:22+08:00

mubaihe349 commented

2026-08-04 11:54:22 +08:00

团队代码文档框架 PRD

版本：1.0
日期：2026-08-04
状态：已完成框架搭建，待团队持续采用
面向成员：yhc、gmy、yzh、cxc 及各自使用的 Agent

1. 背景与问题

四名成员在不同分支使用 Agent 协助开发。代码、进度、实验和决策如果只存在于个人对话或单一流水文档中，新的 Agent 无法快速恢复上下文，也容易误判队友进度、贡献归属和测试状态。

需要一套轻量、可复核的文档框架，使 Agent 在改代码前主动读取已有沉淀，并在完成实际工作后把新事实交接给团队。

2. 目标

为所有 Agent 提供唯一、明确的开工读取协议。
按信息用途分离项目事实、计划、成员进度、实验和决策。
按实际修改人记录代码工作，并区分实际修改人、Git Author/Committer 和合入人。
让正确性、性能和环境结论能够追溯到分支、Commit、命令与结果。
将团队共享事实与 yhc 的个人学习、简历和面试材料分离。

3. 非目标

不替代官方夏令营指南、PR 模板、代码 Review 或 Git 历史。
不要求记录临时聊天、逐行代码讨论或巨大原始日志。
不建设自动同步、机器人提醒、Web 页面或额外文档平台。
不要求成员读取与当前任务无关的全部历史文档。

4. 用户与核心场景

用户	核心场景
当前开发成员及 Agent	开工前恢复项目和本人分支上下文，收尾时留下可交接记录
队友或接手者	读取成员交接、相关实验和决策，理解真实进度与下一步
组长/仓库主	查看各成员分支、修改范围、验证证据和阻塞项
yhc	在团队文档之外整理个人问题、简历素材和面试复盘

5. 功能需求

FR-1：统一启动协议

仓库根目录必须存在 AGENTS.md，明确规则优先级、四名成员及固定分支、开工阅读顺序、双 PR 工程约束、文档更新动作和远端操作边界。

FR-2：唯一团队入口

DOCS/README.md 必须说明各目录用途和最小阅读路径，并链接极简上手说明及必要项目文档。

FR-3：按职责归档

团队文档必须按以下职责维护：

project/：稳定项目事实和成员入口；
plans/：未来阶段、门禁与验收方式；
handoff/：按成员维护实际修改、状态、下一步和阻塞；
experiments/：可复现的环境、测试与性能证据；
decisions/：影响多人或后续工作的关键决定。

每级文件夹必须有简洁 README.md 说明用途和记录格式。

FR-4：实际修改归属

每次修改代码、脚本、Manifest、测试或 Benchmark 后，实际修改人的交接文档必须及时记录日期、分支、Commit/工作区、文件范围、行为变化和验证。实际修改人、Git Author/Committer 与合入人不一致时必须分别标明，并在相关成员交接中交叉记录。

FR-5：证据约束

“已完成”必须有代码、Commit、命令或实验依据。实验必须记录执行人、被测 SHA、环境、输入、完整命令、退出码、结果、结论和限制；没有执行的项目写“未测试”。

FR-6：个人文档隔离

YHC_DOCS/ 只保存 yhc 的问题、专题、简历和面试材��，不作为团队进度或验收证据。值得共享的内容须核实后提炼到 DOCS/。

6. 信息结构

AGENTS.md
DOCS/
├── README.md
├── QUICKSTART.md
├── project/
├── plans/
├── handoff/
├── experiments/
└── decisions/
YHC_DOCS/                 # yhc 本地个人沉淀

7. 标准工作流

Agent 查看分支和工作区，读取 AGENTS.md。
Agent 读取 DOCS/README.md、本人交接和当前任务相关文档。
Agent 阅读官方要求及目标代码附近的 Manifest、测试、Benchmark 和参考实现。
Agent 完成实现与验证，不把未知结果写成完成。
Agent 更新实际修改记录；有实验或关键决策时同步对应文档。
Agent 向用户汇报改动、验证、风险和下一门禁。

8. 验收标准

根目录 AGENTS.md 包含四名成员、角色、固定分支和强制阅读/记录规则。
DOCS/ 各职责目录及其 README.md 齐全，内部链接有效。
每名成员都有独立交接文件，并包含“实际代码修改记录”。
能区分计划、真实进展、实验结果、团队决策和个人笔记。
已知的跨成员贡献在双方交接中注明实际修改人和 Git 提交身份。
文档通过仓库 pre-commit、git diff --check 和相对链接检查。

9. 风险与维护

文档过期：每次实际修改后和任务收尾前更新本人交接。
重复记录：动态状态只保留在成员交接，实验数据只保留在实验文档，其他位置使用链接。
无证据结论：未知内容明确标记“待确认”或“未测试”。
文档负担过重：只记录可交接的事实、证据、决定和下一步，不记录完整聊天与流水操作。

本框架由团队共同维护；官方要求变化时，先更新 AGENTS.md 和受影响的公共文档，再继续开发。

合并请求描述

[简要描述本次合并请求的目的和主要内容]

变更内容

1. 增强了xxx

# 团队代码文档框架 PRD - 版本：1.0 - 日期：2026-08-04 - 状态：已完成框架搭建，待团队持续采用 - 面向成员：yhc、gmy、yzh、cxc 及各自使用的 Agent ## 1. 背景与问题四名成员在不同分支使用 Agent 协助开发。代码、进度、实验和决策如果只存在于个人对话或单一流水文档中，新的 Agent 无法快速恢复上下文，也容易误判队友进度、贡献归属和测试状态。需要一套轻量、可复核的文档框架，使 Agent 在改代码前主动读取已有沉淀，并在完成实际工作后把新事实交接给团队。 ## 2. 目标 - 为所有 Agent 提供唯一、明确的开工读取协议。 - 按信息用途分离项目事实、计划、成员进度、实验和决策。 - 按实际修改人记录代码工作，并区分实际修改人、Git Author/Committer 和合入人。 - 让正确性、性能和环境结论能够追溯到分支、Commit、命令与结果。 - 将团队共享事实与 yhc 的个人学习、简历和面试材料分离。 ## 3. 非目标 - 不替代官方夏令营指南、PR 模板、代码 Review 或 Git 历史。 - 不要求记录临时聊天、逐行代码讨论或巨大原始日志。 - 不建设自动同步、机器人提醒、Web 页面或额外文档平台。 - 不要求成员读取与当前任务无关的全部历史文档。 ## 4. 用户与核心场景 | 用户 | 核心场景 | | -------------------- | ---------------------------------------------------- | | 当前开发成员及 Agent | 开工前恢复项目和本人分支上下文，收尾时留下可交接记录 | | 队友或接手者 | 读取成员交接、相关实验和决策，理解真实进度与下一步 | | 组长/仓库主 | 查看各成员分支、修改范围、验证证据和阻塞项 | | yhc | 在团队文档之外整理个人问题、简历素材和面试复盘 | ## 5. 功能需求 ### FR-1：统一启动协议仓库根目录必须存在 `AGENTS.md`，明确规则优先级、四名成员及固定分支、开工阅读顺序、双 PR 工程约束、文档更新动作和远端操作边界。 ### FR-2：唯一团队入口 `DOCS/README.md` 必须说明各目录用途和最小阅读路径，并链接极简上手说明及必要项目文档。 ### FR-3：按职责归档团队文档必须按以下职责维护： - `project/`：稳定项目事实和成员入口； - `plans/`：未来阶段、门禁与验收方式； - `handoff/`：按成员维护实际修改、状态、下一步和阻塞； - `experiments/`：可复现的环境、测试与性能证据； - `decisions/`：影响多人或后续工作的关键决定。每级文件夹必须有简洁 `README.md` 说明用途和记录格式。 ### FR-4：实际修改归属每次修改代码、脚本、Manifest、测试或 Benchmark 后，实际修改人的交接文档必须及时记录日期、分支、Commit/工作区、文件范围、行为变化和验证。实际修改人、Git Author/Committer 与合入人不一致时必须分别标明，并在相关成员交接中交叉记录。 ### FR-5：证据约束 “已完成”必须有代码、Commit、命令或实验依据。实验必须记录执行人、被测 SHA、环境、输入、完整命令、退出码、结果、结论和限制；没有执行的项目写“未测试”。 ### FR-6：个人文档隔离 `YHC_DOCS/` 只保存 yhc 的问题、专题、简历和面试材��，不作为团队进度或验收证据。值得共享的内容须核实后提炼到 `DOCS/`。 ## 6. 信息结构 ```text AGENTS.md DOCS/ ├── README.md ├── QUICKSTART.md ├── project/ ├── plans/ ├── handoff/ ├── experiments/ └── decisions/ YHC_DOCS/ # yhc 本地个人沉淀 ``` ## 7. 标准工作流 1. Agent 查看分支和工作区，读取 `AGENTS.md`。 1. Agent 读取 `DOCS/README.md`、本人交接和当前任务相关文档。 1. Agent 阅读官方要求及目标代码附近的 Manifest、测试、Benchmark 和参考实现。 1. Agent 完成实现与验证，不把未知结果写成完成。 1. Agent 更新实际修改记录；有实验或关键决策时同步对应文档。 1. Agent 向用户汇报改动、验证、风险和下一门禁。 ## 8. 验收标准 - 根目录 `AGENTS.md` 包含四名成员、角色、固定分支和强制阅读/记录规则。 - `DOCS/` 各职责目录及其 `README.md` 齐全，内部链接有效。 - 每名成员都有独立交接文件，并包含“实际代码修改记录”。 - 能区分计划、真实进展、实验结果、团队决策和个人笔记。 - 已知的跨成员贡献在双方交接中注明实际修改人和 Git 提交身份。 - 文档通过仓库 pre-commit、`git diff --check` 和相对链接检查。 ## 9. 风险与维护 - **文档过期**：每次实际修改后和任务收尾前更新本人交接。 - **重复记录**：动态状态只保留在成员交接，实验数据只保留在实验文档，其他位置使用链接。 - **无证据结论**：未知内容明确标记“待确认”或“未测试”。 - **文档负担过重**：只记录可交接的事实、证据、决定和下一步，不记录完整聊天与流水操作。本框架由团队共同维护；官方要求变化时，先更新 `AGENTS.md` 和受影响的公共文档，再继续开发。 ## 合并请求描述 [简要描述本次合并请求的目的和主要内容] ## 相关Issue 关联Issue编号：#{Issue编号} ## 变更内容 ### 1. 增强了xxx

mubaihe349 added 1 commit 2026-08-04 11:54:23 +08:00

auto-label / apply-label (pull_request) Has been cancelled Details

dcf3dcc71b 团队文档规范框架_8.4

mubaihe349 merged commit 34cfcd1ad8 into feat/moe_topk_sum_group_idx

2026-08-04 13:33:17 +08:00

mubaihe349 referenced this issue from a commit

2026-08-04 13:33:18 +08:00

Merge pull request '团队协作文档规范框架搭建' (#1) from dev/yhc into feat/moe_topk_sum_group_idx

Sign in to join this conversation.

No reviewers

No Label

No Milestone

No project

No Assignees

1 Participants

Notifications

Due Date

The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: supernova1896/TileOPs-Metax#1