Workspace 实践:从个人提效到组织提效



导读 
introduction

个人提效不等于组织提效。一个人变成「超级兵」并不能提升团队的需求交付数据。本文讲清三件卡在中间的事,以及我们用 Workspace 这个「面向 Agent 的组织资产基座」怎么解。


全文 16884 字,预计阅读时间 9 分钟
GEEK TALK

01

业务提效的困境


三类卡点挡在团队吞吐前面:个人经验难以复制、跨角色背景对齐成本高、工具生态各自为政。

三类卡点:卡在哪里,代价是什么

三个卡点的共同点:它们都不是「模型不够强」造成的,换更强的模型也不会消失。

1.1 个人经验难以复制

前几天我用 iCafe 的 skill 批量获取卡片信息时遇到 403 权限错误,但我是空间管理员,肯定是有权限的,研究了一会儿发现其实等几秒再执行就好了。找 iCafe 的值班同学确认过,真实原因是后端的接口限流,跟权限没关系。所以我在自己的 CLAUDE.md 里加了一条规则:

当 iCafe 返回 403 时做最多两次重试,分别 sleep 3 秒和 5 秒,如果依旧报错则按失败处理。

其他人遇到同样的报错,得把我走过的流程以及踩过的坑重走一遍,甚至可能真以为是权限不够,然后 Agent 就卡在那里不动了。

问题

这种经验如果分享出去是可以解决效率问题的,但我要怎么把这个经验低成本传播给团队里其他人?

1.2 更高效的沟通方式

我们现在一个需求从前到后需要开很多对齐会议:PRD 评审、代码设计评审、前后端接口对齐会、测试同学的 case list 评审。只要涉及角色之间的配合就得约人,约之前还得先准备一堆文档,开完会还可能得再改几版然后再对齐,还没开始干活,人已经疲了。

从有效信息交流上看这些会真正在做两件事:

整个需求交付过程中,背景对齐这一段是最难压缩的。如果事事对齐,那会消耗大量时间同时成为流程运转的主要瓶颈,如果不对齐,那么方案是否清晰、决策是否合理这些无法引入对抗视角,最后交付产出可能不符合预期。

问题

多角色之间如何高效沟通协作?

1.3 割裂的工具生态

结果就是一个人在 Claude 上做了一套非常好用的 skill 集合,其他人在 Comate、Codex 上没法用,或者效果很差。

问题

能不能构建一套与具体 Harness / Agent 无关的基座,让各个 harness / agent 都能运行在上边?

GEEK TALK

02

我们早期的探索与尝试


2.1 第一版尝试:Devflow

一开始我们基于 SDD 理念,在内部的 Agent 平台上搭建了一套研发工作流,叫 devflow。那会儿公司内部的 agent、skill、mcp 这些基建都还不太成熟,模型上下文普遍才 128k,openclaw 也才刚火起来。但这套东西到现在来看依旧有两个地方我觉得很有价值:

✅ 厂内生态接得比较深

通过提示词让 Agent 知道 iCafe、iCode、知识库、iAPI 这些都是干啥的,它能自己去取需求、取接口契约、写完代码提评审,可以理解为一个百度 Native 的研发工作流。

✅ 工作流框架的约束力

讨论、设计、编码、测试、评审修改、合入、整理文档,每个阶段都有硬门禁,必须先做完这一步才能做下一步。这是在大模型能力不稳定的情况下,让交付质量相对稳定产出的有效方式。

并且在那个时候,我们就已经初步有了构建Workspace的概念。

2.2 个人跑的飞快,但团队没有跟上

有了devflow之后,写代码基本就可以自动跑起来了,我可以用tmux同时开三到五个终端会话去聊问题、评审设计,然后让他自己去开发,这一套下来我个人的产出量确实涨了,但从整个团队看,需求交付的数据没什么改善。

纵向的短板决定交付周期,横向的断点决定经验能不能变成组织能力。两条路都不通,个人产出涨了也传导不到团队数据上。

2.3 组织提效要解决的四件事

1. 团队资产怎么攒起来

意识到上下文对LLM的重要性后,团队第一步工作就是文档工程,而且得找到一个低成本把每个人脑子里的经验记下来的办法。低成本这三个字是关键,不然它一定会被本职工作挤掉。

2. 攒起来的东西怎么流动

前人写的文档、报告、代码和经验,后人得能用上;新产生的信息、经验、设计决策也得能及时写回去。东西要用起来才能产生新的价值,所以要怎么让这些资产流动起来?

3. 流程和角色职责变化

当AI对不同角色的生产效率提升出现了明显的差异后,角色关系就需要进行调整以适应这样的变化。

这件事往往连着角色的重新划分 —— 谁写测试、谁做评审、谁对质量负责,这些边界在 AI 进来之后都会挪位置。

4. 交付质量要持续稳定

让AI自由发挥,可能这一次写出非常完美的逻辑,但下一次写出来的东西完全没法用;不同人、不同Harness、不同Workflow、不同的模型对交付结果的影响可能很大,而我们需要构建的是一个在一定范围内产出相对稳定可靠的结果。


当然这些问题不仅仅是我们遇到了,很多在推进组织提效的团队都遇到了这样的问题,在各自摸索了一段时间之后,我们探索出来的解法大同小异 —— Workspace!

GEEK TALK

03

殊途同归的解法:Workspace


3.1 Workspace 是什么

它不是文档库,不是 skill 库,也不是把几个仓库放在一起。它解决的是组织资产用什么形式组织、怎么流动的问题,文档、skill、代码库都算在里面。它是面向 Agent 的组织资产基座,Agent 通过它了解业务、参与业务。

简单来说,它会把团队的如流知识库、代码库、iCafe 空间、skill 都放到一个代码库下面。Agent 在这个库里能访问到所有业务资产,还能自行验证产出是否正确。也正是因此可能很多人会把Workspace和知识库、Skill、代码仓库这些概念混淆。

另外有一个很重要的实践经验:Workspace不存知识的快照或者备份,只存摘要和索引。所以其实不是把外部的知识库、代码库以及卡片内容整理成文本存储到Workspace中,而是构建外部资产的索引,让Agent知道查询某个问题应该去哪些平台上获取,也就是说,我们固有的流程和方式都没变,依旧是在知识库写文档、iCafe记录任务,这也是Workspace能推广起来的重要原因,Workspace不直接改变你的工作模式。

3.2 一个俄罗斯方块游戏的Workspace示例

以下通过一个网页版俄罗斯方块游戏的 Workspace 来演示一个最小Workspace的结构原理。

组织结构

tetris-workspace/├── README.md# 唯一源:workspace 组织 + Agent 规则├── AGENTS.md -> README.md├── CLAUDE.md -> README.md├── .claude/# 三端桥接,只放软链│   ├── skills -> ../skills│   └── agents -> ../agents├── .codex/        (同上)├── .comate/       (同上)├── agents/│   └── tetris-playtester.md# 一个自动运行游戏并检查问题的 agent├── docs/│   ├── README.md# 路由表,不放内容│   ├── INDEX.md# 资产索引,一行一条,供精确检索│   ├── LOG.md# 资产维护日志,四次迭代各一段│   ├── knowledge/# 俄罗斯方块游戏相关的知识和概念等│   │   ├── sources.md# 外部平台入口│   │   ├── tetris-rules.md# 概念:SRS 旋转、消行判定、锁延迟│   │   └── experience-wallkick.md# 经验:踢墙表为什么不能自己编│   └── activity/# 研发活动记录│       ├── 20260701-iter1-mvp.md│       ├── 20260710-iter2-hold-and-ghost.md│       ├── 20260718-iter3-fix-rotate-through-wall.md│       └── 20260725-iter4-score-and-difficulty.md├── skills/│   ├── ku-doc-manage/│   ├── icafe-official/│   ├── icode/│   └── summarize/# 完整正文,闭环关键└── repos/    └── tetris-game/# 游戏代码库,通过 git submodule 引入

可以看到,这个 workspace 把 docs 分成了知识(knowledge)与活动记录(activity)两个子目录:知识层放游戏术语、规则、经验等长期有效的内容,活动层按时间记录了四次研发迭代。

另外通过软链把 agents 和 skills 适配给 Claude / Codex / Comate 等 harness,新增 agent 或 skill 时只需要改一个地方,解决了多种工具生态问题。

几个重要文件

四个文件各自解决什么问题

README.md —— 规则唯一源·三端共读

# Tetris Workspace
这是一个用于演示 Workspace 结构的示例项目。业务对象是一个俄罗斯方块小游戏,从立项到四次迭代的完整历史都沉淀在这个库里。> 重要:`AGENTS.md` 与 `CLAUDE.md` 都是指向 `README.md` 的软链。**规则只在 `README.md` 维护**,不要改软链、不要把软链替换成副本、不要在软链目标之外另写一份规则。
## 目录结构
```tetris-workspace/├── README.md                          # 唯一源:workspace 组织 + Agent 规则├── AGENTS.md -> README.md├── CLAUDE.md -> README.md├── .claude/                           # 三端桥接,只放软链│   ├── skills -> ../skills│   └── agents -> ../agents├── .codex/     (同上)├── .comate/    (同上)├── agents/│   └── tetris-playtester.md├── docs/│   ├── README.md                      # 路由表,不放内容│   ├── INDEX.md                       # 资产索引│   ├── LOG.md                         # 资产维护日志│   ├── knowledge/│   └── activity/├── skills/└── repos/    └── tetris-game/```
## 查询信息先读 docs/README.md
任何信息查询一律先读 `docs/README.md`,它是 `docs/` 的唯一入口与路由表。**不要凭印象直接猜文件路径。**外部平台是权威源,`docs/` 只是索引层与本地沉淀层。卡片状态、知识库正文、代码提交记录都以外部平台的实时数据为准。
## 改代码之前先读 repos/tetris-game/AGENTS.md
`repos/` 下的仓库以 submodule 引入,在本 workspace 内只读。修改代码要进入源码仓库自身的 checkout,并遵循它的 `AGENTS.md`。
## 一次迭代怎么结束
每次迭代走完设计、开发、测试、合入之后,必须调用 `summarize` skill 收尾。它负责判断这次产生的东西该进 `knowledge/` 还是 `activity/`,并同步 `INDEX.md` 和 `LOG.md`。**写回不靠自觉,它是流程里的强制阶段。** 一次迭代没有 `summarize` 就不算结束。
## 分层规则
`docs/` 下只有两层,按内容**会怎样失效**划分,不按主题划分:| 层 | 目录 | 放什么 | 什么时候会失效 ||---|---|---|---|| 知识层 | `docs/knowledge/` | 概念定义、外部系统入口、带条件的经验判断 | 被新证据推翻时;此时要**回头改旧页**,不是另写一页 || 活动层 | `docs/activity/` | 每次迭代做了什么、怎么做的、验证结果 | 不失效,只增不改 |两层都放不下时**停下来问用户**,不要硬塞进最接近的目录。

docs/README.md —— docs 的唯一入口·管路由

# docs 查询入口
本文件是 `docs/` 的唯一查询入口,只描述信息怎么找,不承载动态状态,不复制外部平台内容。外部平台(iCafe 空间、如流知识库、iCode)是权威源,`docs/` 只是索引层与本地沉淀层。
## 外部源
- iCafe 空间:`TETRIS-DEMO`(卡片、迭代、Bug)- iCode 仓库:`demo/tetris-game`- 如流知识库:`https://ku.example-int.com/space/tetris-demo`
## 场景路由
| 我要查什么 | 去哪里 ||---|---|| 精确找某份资产 | `INDEX.md`,用 ripgrep 命中关键词 || 某个约定当初为什么这么定 | `LOG.md`,按日期倒着翻 || 游戏规则、旋转判定、消行判定 | `knowledge/tetris-rules.md` || 外部平台入口、取数方式 | `knowledge/sources.md` || 某个坑踩过没有、某个做法为什么被否掉 | `knowledge/` 下 `experience-*.md` || 某个功能是哪次迭代做的、怎么验证的 | `activity/`,文件名带日期与主题 || 代码在哪、怎么跑测试 | `../repos/tetris/AGENTS.md` |
## 写入规则
- 长期有效的东西进 `knowledge/`,做过的事进 `activity/`。- 旧知识被新证据推翻时**回头改那一页**,并在 `LOG.md` 记一条为什么改。不要另写一页新的留着两份矛盾的真相。- 每次写入都要同步 `INDEX.md` 一行和 `LOG.md` 一段。这由 `summarize` skill 负责,不靠人记。

docs/INDEX.md —— 一行一条资产·供检索

# Workspace 资产索引
## Search Rule
1. 先读本文件,在资产表中找到对应资产;2. 读对应资产获取相关内容。签名列是内容摘要短哈希,用于判断本地缓存是否落后于权威源。
## 资产表
| 类型 | ID | 内容 | 签名 ||---|---|---|---|| 文件 | knowledge/tetris-rules.md | 俄罗斯方块规则:7 种方块、SRS 旋转、消行判定、锁延迟 | a3f19c || 文件 | knowledge/sources.md | 外部平台入口与取数方式:iCafe 空间、iCode 仓库、知识库 | 7b2e04 || 文件 | knowledge/experience-wallkick.md | 经验:踢墙表不能靠模型推导,必须取权威源 | c81d55 || 文件 | activity/20260701-iter1-mvp.md | 迭代一:MVP,方块下落与消行,能玩一局 | 2e90ab || 文件 | activity/20260710-iter2-hold-and-ghost.md | 迭代二:新增 Hold 暂存与 Ghost 落点预览 | 5fc731 || 文件 | activity/20260718-iter3-fix-rotate-through-wall.md | 迭代三:修复靠墙旋转穿墙,根因是踢墙表被编造 | 9d4e18 || 文件 | activity/20260725-iter4-score-and-difficulty.md | 迭代四:计分规则与难度曲线,playtester 取手感数据 | 6a07f2 || 代码 | repos/tetris/src/rotate.js | 旋转与踢墙实现,迭代三的修复落点 | f42b8e || 代码 | repos/tetris/test/rotate.test.js | 旋转回归测试,含迭代三新增的靠墙用例 | 1c6d93 || iCafe | TETRIS-DEMO#12 | Story:俄罗斯方块 MVP | - || iCafe | TETRIS-DEMO#31 | Bug:I 型方块贴右墙旋转后穿出边界 | - || Ku | https://ku.example-int.com/space/tetris-demo/design | 玩法设计文档,迭代一的输入 | 4b8f27 |
docs/LOG.md —— 按日期倒序变更日志·留依据
# 资产维护日志
记录 `docs/` 与索引资产的变更。格式是 `## YYYY-MM-DD` 下挂条目,每条一句话说清改了什么、为什么。它的用处是半年后你还能搞清楚某个约定当初为什么这么定。
## 2026-07-25
- 新增 `activity/20260725-iter4-score-and-difficulty.md`  计分按 1/2/3/4 行给 100/300/500/800,难度按每 10 行提一档速度。  档位是 playtester 跑 20 局之后定的,不是拍的。- `knowledge/sources.md` 补一条:手感数据来自 playtester 输出的  `artifacts/playtest-*.json`,不是人工计时。
## 2026-07-18
- 新增 `knowledge/experience-wallkick.md`  迭代三根因:迭代一的踢墙表是模型按对称性推出来的,看着合理但与 SRS 不符。  结论是这类查表数据必须取权威源,不能推导。- **回头改了** `knowledge/tetris-rules.md` 的旋转小节  原文那张踢墙表整个是错的,替换为 SRS 标准表并注明来源。  这是本 workspace 第一次出现知识页被新证据推翻,保留这条记录作为范例。- 新增 `activity/20260718-iter3-fix-rotate-through-wall.md`
## 2026-07-10
- 新增 `activity/20260710-iter2-hold-and-ghost.md`  这次迭代**没有产生新的知识页**。Hold 与 Ghost 都是直接照设计文档实现,  没遇到需要判断的地方。不往 `knowledge/` 硬塞内容也是正常结果。
## 2026-07-01
- 建库。`README.md` 定下两层分法与 `summarize` 强制收尾规则。- 新增 `knowledge/tetris-rules.md`,从玩法设计文档提炼概念定义。- 新增 `knowledge/sources.md`,登记 iCafe 空间、iCode 仓库、知识库入口。- 新增 `activity/20260701-iter1-mvp.md`  MVP 范围定为下落、移动、旋转、消行、结束判定,不含计分。

最重要的一环:summarize skill

Workspace 能不能越来越好用,关键就在于有没有这个 skill,以及这个 skill 设计得好不好。

我们先来看这个 skill 的内容。

skills/summarize/SKILL.md

---name: summarizedescription: 把一次迭代产生的可复用内容写回 workspace。每次迭代收尾必须调用,是资产流动闭环的最后一环。用户说「收尾」「总结一下」「沉淀」,或一次迭代的开发、测试、合入都已完成时使用。---
# 迭代收尾写回
**这是 workspace 中最重要的 skill。** 前面几个 skill 负责查,这一个负责写回。没有写回,Agent 每次都从零开始,workspace 就退化成一个静态文档库。
## 前置条件
调用前确认这次迭代的开发、测试、合入都已完成。中途调用会写进未定型的结论,比不写更糟 —— 错的结论会被下次检索命中并当依据用。
## 自主原则
**默认自己决策,不问用户。** 写什么、放哪层、叫什么文件名、`LOG.md` 那句话怎么写,全部自行判断并直接落盘。用户已经在这次迭代里给过足够信息,收尾阶段再回头逐项确认,等于把成本从 Agent 转回人身上 —— 写回一旦变成一道需要人配合的手续,它就会被跳过,闭环也就断了。
判断不确定时按「先写下来,标明不确定」处理,不要为了求稳而不写。写进去的内容可以被下一次迭代修正,没写下来的东西下次就不存在了。
只有两种情况停下来问用户:
1. **要做的事违背 `README.md` 里的分层规则或本 skill 的边界** —— 比如内容两层都放不下、需要新建 `docs/` 一级目录、需要改分层规则本身。2. **要写进 knowledge 层的结论与用户在本次会话中明确表达的判断相冲突** —— 这种冲突不能由 Agent 单方面裁决。
除此之外一律自行决定。**分不清该进哪一层不是提问的理由**,按第 2 步的分流表判断;表里给不出唯一答案时进 activity 层,那里的内容不失效,代价最小。
## 步骤
### 1. 判断这次产生了什么
逐项过一遍,别凭印象:
- 有没有遇到需要判断的地方,判断依据是什么- 有没有踩坑,坑的触发条件是什么- 有没有推翻之前的某个结论- 有没有新的外部数据来源- 具体做了什么、怎么验证的
### 2. 分流
| 这次产生的东西 | 落点 ||---|---|| 客观事实、概念定义、规则 | `docs/knowledge/` 对应概念页 || 带条件的判断、踩过的坑 | `docs/knowl…
— 以上为试看内容(约 40%),开通会员后阅读全文 —