Agent Workspace：组织长期工作环境与任务现场

概述

在一个持续参与的项目里，如何让 Agent 找到正确的项目事实、使用已有工具完成工作，并把确认过的经验留给下一次任务？本文从这些研发现场的问题出发，介绍我目前采用的两层组织方式：长期维护的 Workspace，以及围绕单项任务建立、结束后归档的 Execution Workspace。

不同产品对 Workspace 有各自的定义。本文采用我在个人研发实践中的模型；文中的目录、字段和跨仓需求都是说明模型的简化示例。

一、研发现场中的系统缺口

同一个项目里，新的 Agent 会话经常需要重新了解仓库职责、业务约定、构建方式和历史问题。即使这些材料已经存在，如果入口不清楚、执行方法不可用、验收要求没有定义，任务仍会反复依赖人的补充。

这些问题暴露出研发工作环境中的几类系统缺口：

模型看不到的事实、运行环境中不可用的工具，以及尚未定义的验收标准，都需要在项目工作环境中补上。更强的推理能力可以帮助分析问题，但这些工作条件仍需要有人组织和维护。

因此，这套模型要解决的是一条连续链路：让 Agent 知道去哪里查、如何执行、怎样证明完成，以及哪些经验值得留下。

这些内容又有不同的生命周期。仓库职责、业务规则和验证方法需要跨任务维护；本次目标、方案选择、代码改动和运行证据则围绕一项任务积累。把它们分别组织起来，才能既保持任务连续性，又让经过确认的内容持续复用。

二、两层 Workspace 的职责与生命周期

我目前采用的基本形式是：Workspace 用文件夹承载，通过版本控制长期演进；Execution Workspace 围绕一项任务建立，任务结束后归档。两层都包含上下文、能力和治理。

Workspace 组织跨任务持续使用的项目知识、工具方法和工作规则。仓库地图、业务说明、Skills、脚本、验证入口和环境使用方法都可以在这里维护，供后续任务按需使用。

Execution Workspace 组织一项任务从开始到结束所需的材料与执行资源，包括本次目标、需求规格（Spec）、方案、决策、工作目录、工具连接、运行过程和验证证据。任务完成或明确终止后，这个现场结束活跃使用，相关记录归档。

例如，“应用仓和共享模块分别负责什么”适合长期维护；“这次需要修改哪两个模块、方案为什么调整、测试结果是什么”属于任务现场。

两层的内容都可以从上下文、能力和治理三个维度理解。下图展示的是这三个维度在不同范围中的具体化：

长期层维护可复用的知识、方法和规则，执行层结合本次任务选择和落实。图中的“按任务装配”包括读取相关知识、启用所需能力、确认执行边界，并加入本次需求和约束。

三、长期 Workspace 的资产组织与版本演进

三个维度与五类资产

上下文回答项目是什么、事实在哪里；能力回答工作怎样执行；治理回答执行边界、继续条件和完成要求。为了检查长期环境是否完整，可以进一步从代码、知识、环境、工具、流程五类内容整理资产：

五类资产用于检查内容是否齐备，三个维度用于理解它们怎样发挥作用。它们共同描述长期 Workspace 的组成，实际组织文件时可以按项目和维护方式安排。

图中代码、知识、环境主要提供上下文，工具支持执行，流程组织工作约束和验证要求。同一项资产也可以跨越多个维度：一个 Skill 可以同时包含业务知识、操作步骤和验收要求，一条 Hook 可以执行流程中的检查。

上下文：建立查询路由

长期上下文帮助 Agent 理解代码分布、模块依赖和业务概念，并找到相关资料。这些内容可以直接保存在 Workspace 中，也可以通过索引连接到权威来源。业务代码由各自仓库维护，正式接口文档由原系统管理，Workspace 记录职责、路径、适用范围和查询方式。

这里需要区分知识与当前状态。架构约定、已确认的业务规则和排障方法适合长期维护；需求进度、运行日志、构建状态和环境故障需要在使用时查询。查询结果应连同来源、参数和时间留在本次任务中。

入口文件负责引导查阅。它应说明先看哪张仓库地图、到哪里查业务规则、哪些资料只在特定任务中读取，让 Agent 能从少量入口找到需要的内容。

能力与治理：连接方法、资源和完成要求

Skills 可以描述一类任务的处理流程，脚本承担构建、检查、数据转换等可重复动作，工具连接帮助访问需求、知识库、评审和日志系统。Plugins 可以组织一组相关能力，Hook 则可以在所用客户端支持的事件上执行检查或记录。

方法文件需要与实际运行资源连接。一个验证 Skill 可能依赖脚本、测试设备和外部服务，Workspace 应说明依赖、准备步骤和可用性检查。环境说明随长期内容维护，实际凭据通过运行环境提供。

个人 Workspace 中的治理可以落实为具体约定：修改前读取哪些仓库规则，允许操作什么范围，什么动作需要确认，各阶段产出什么，以及交付需要哪些证据。涉及文件访问和外部操作的权限，还需要在实际运行环境中配置；规则文件负责表达约束，运行环境负责落实权限。

版本演进：记录工作环境的变化

文件夹给知识、规则和方法提供稳定位置，版本控制记录它们的变化。修正一条仓库说明、补充一项测试方法、调整一个 Skill，都可以形成可追溯的提交，必要时比较或撤回。

长期维护的内容也有适用条件。涉及具体模块、接口或版本的说明，应保留来源和适用范围；原始实现变化后，相关说明需要重新核对。

这套版本历史管理的是工作环境的定义与资产。外部系统的实时状态、正在运行的进程和临时测试数据，仍由执行时的查询与记录补充。

四、长期 Workspace 的划分依据

一个 Workspace 应覆盖多大的范围，可以从共同维护的项目知识、规则和方法来判断。范围过大，任务容易混入其他项目的背景与约束；范围过小，一个经常发生的跨仓需求又需要反复拼接资料。

在个人研发场景中，可以用四项条件检查这个范围：

这四项是组织范围的检查方法。一个 Workspace 内仍可以有按仓库、模块和环境区分的规则与权限，任务只使用其中与自身相关的部分。

例如，一个客户端产品的应用仓、共享模块仓和配置仓，可以在同一个长期 Workspace 中组织，分别记录各仓的职责和验证入口。一项任务需要改动多个仓库时，就能沿同一张地图找到它们。

同一个人还可能承担离线数据分析。如果它的业务口径、数据权限、工具和更新方式明显不同，单独维护更便于选择正确的默认上下文。两类工作仍然可以复用目录模板、通用脚本或工具连接；具体项目事实与适用规则保留各自的维护位置。

五、Execution Workspace 的任务边界

Execution Workspace 中的“单次”，以一项任务的工作周期为边界。任务可能包含需求澄清、方案设计、实现、评审、验证和返工，也可能跨越多天与多个 Agent 会话（Session）。

一个 Session 结束后，可以在同一任务现场中继续工作。已有材料应使后续会话能够恢复目标、当前进度、关键决策和待处理问题。

假设有一个需求：客户端新增一种卡片展示，共享模块负责数据解析，应用仓负责界面呈现。本次 Spec、字段样例、实现方案、两个仓库的改动和验证报告，都围绕同一项任务组织。

任务现场可以关联多个代码目录。需要并行隔离时，可以使用独立工作目录、Worktree 或沙盒；直接在现有代码目录中操作时，也应记录实际路径与分支，避免不同任务的改动混在一起。

任务目录本身可以主要保存材料与索引，代码和运行资源通过明确的路径关联。Execution Workspace 的范围由这项任务使用的上下文、能力和执行约束共同确定。

六、目录布局与上下文加载

用目录表达两种生命周期

下面的示例布局把长期环境与任务目录分开。目录名称可以调整，关键是能判断内容归属，以及它应如何维护。

agent-work/
├── workspace/
│   ├── AGENTS.md
│   ├── repos/
│   │   ├── index.md
│   │   └── shared-card.md
│   ├── docs/
│   ├── rules/
│   ├── skills/
│   ├── scripts/
│   └── workflows/
└── executions/
    └── card-display/
        ├── task.md
        ├── spec.md
        ├── decisions.md
        ├── progress.md
        ├── environment.md
        └── evidence/

示例中的 workspace/ 单独纳入版本控制。AGENTS.md 保存入口说明，repos/index.md 记录仓库职责与路径，各仓说明补充启动和测试方式。docs/、rules/、skills/ 和 scripts/ 分别组织知识、规则、方法与可执行动作，workflows/ 记录阶段衔接和完成要求。工具配置或通用能力也可以保存在外部，由入口文件说明位置。

executions/card-display/ 保存这项任务的目标、Spec、决策、进度、环境记录和证据。实际使用时，任务目录可以放在自己的需求交付目录中，通过路径关联长期 Workspace；归档材料也可以按需单独进行版本管理。

这是一份内容布局示例。建设时先建立入口和当前流程需要的文件，其他目录随实际使用逐步补充。

建立从任务到长期环境的入口

从任务目录启动时，可以通过首条指令、入口文件或启动脚本，先读取任务说明，再沿路径读取长期 Workspace 的入口与索引。入口文件名、自动发现范围和配置挂载方式按所用客户端确定。

入口说明应能帮助 Agent 找到相关仓库、判断哪些资料需要读取、使用哪些能力，以及遵守哪些规则。任务归档与其他项目资料可以通过索引查找，在有关联时再读取。

task.md 可以记录任务需要关联的长期环境、代码仓库和证据位置，实际加载由入口指令或脚本落实。下面的 YAML 是一种说明性的记录格式，路径与提交号均为示例，所有相对路径都以当前任务目录为基准：

task: card-display
workspace:
  path: ../../workspace
  revision: 9f2c7b1
repositories:
  - path: /code/shared-card
    base_revision: a13e2d4
  - path: /code/client-app
    base_revision: b24f3e5
evidence_path: ./evidence

记录版本并落实执行条件

需要追溯任务时，可以记录所使用的 Workspace 提交版本，以及各代码仓库的起始版本。要求固定版本时，实际读取的内容也应来自对应检出版本或独立副本。任务中途更新规则或切换工具方法时，同步更新版本记录与调整原因，供后续会话恢复现场。

本次使用的外置 Skill、脚本或文档也应纳入追溯范围，可以记录它们的版本或内容快照；实时查询则保留来源、参数与时间。这些信息与 Workspace 提交共同描述任务当时使用的知识和方法。

运行前还应确认代码目录、工具连接、依赖和测试环境是否可用，并落实本次操作权限。环境说明可以随版本维护，实际凭据通过运行环境提供。

七、一次研发任务中的交付闭环

仍以新增卡片展示为例。长期 Workspace 已经记录仓库职责、字段约定、构建方法和常用验证能力；Execution Workspace 在此基础上组织这次具体工作。

交付过程需要说明每个阶段的输入、使用的能力、产物和退出条件。下面用一条简化链路表示它们的关系：

长期 Workspace 提供知识、方法和规则，具体执行与证据保存在本次任务现场。Review 检查代码并处理评审意见，Verify 按验收条件验证结果；两者发现的阻塞问题都需要返回诊断和实现。

创建现场并形成 Spec

任务开始时，建立需求目录，保存目标、输入材料和验收条件。Agent 根据仓库索引定位共享模块与应用仓，读取相关约定，并查询当前需求和代码状态。

随后形成 Spec：新卡片在什么条件下展示，字段缺失时怎样处理，哪些已有行为需要保持，怎样验证。讨论中的选择和变更记录在任务现场，供实现和验收共同使用。

选择能力并完成实现

根据任务范围，启用共享模块修改方法、界面实现方法、构建脚本和测试工具。长期层提供通用做法，本次使用的路径、分支、环境差异与额外约束留在任务记录中。

Agent 分别修改数据解析与界面呈现，执行相关检查，再依据评审意见修复。代码差异（Diff）、评审结论和未解决问题与任务关联，后续会话可以继续处理。

按验收条件验证

验证阶段逐项检查 Spec 中的要求。例如，新卡片是否按约定展示，缺失字段是否正确处理，原有卡片是否保持预期行为。

每项结论关联可复查的证据，包括测试结果、请求与响应、界面截图或运行日志。验证方法应写清使用哪个环境、执行什么步骤、期望结果是什么，以及怎样保存证据。

例如，字段兼容要求可以对应缺失字段样例和解析测试结果，界面展示要求可以对应测试环境中的操作记录与截图，已有行为则通过相关回归用例确认。每条验收条件分别记录结果，构建成功不能覆盖界面验证失败。

涉及真实环境的行为，应在对应环境中确认。验证通过后进入交付，仍有失败项时继续诊断和实现。任务若明确终止，则记录未完成项、终止原因和后续动作，并以终止状态归档。

保持跨会话的任务连续性

如果任务需要换一个 Session 继续，应在任务材料中更新当前进度、已经确认的决策、剩余问题和验证状态。新的会话通过这些记录恢复工作，再按需查阅原始讨论与执行证据。

整个过程中，长期 Workspace 的内容服务于这次任务；任务中新出现的假设、试验和环境观察先留在本次现场，待核实后再判断是否适合长期维护。

八、任务归档与经验回写

任务结束后，有两项需要分别处理的工作：保存可追溯的任务档案，以及识别可以改进长期环境的内容。归档可以在每项任务结束时完成，经验回写则取决于本次是否产生了值得复用的知识或方法。

任务档案保留本次目标、过程与结果，可复用内容则经过提炼与确认后进入长期 Workspace。后续任务按需查阅归档，使用更新后的知识和能力开展工作。

归档保存任务过程与交付索引

归档材料应能回答：任务目标是什么，最终采用什么方案，修改了哪些内容，如何验证，还有哪些遗留事项。提交、评审记录、报告和相关证据可以保存为文件，也可以通过稳定链接关联。

代码改动继续按代码仓库的交付流程处理。归档索引记录它们的去向，临时进程、测试服务和工作目录则按需清理。需要追溯的环境信息应先转成记录，不能依赖某个终端或进程一直存在。

“结束即归档”表示这个现场结束活跃执行。以后如果需要追溯问题，仍然可以通过索引读取材料；归档内容不作为所有新任务的默认上下文。

回写经过核实的可复用内容

新增卡片的任务可能暴露一条此前未记录的字段兼容约定，也可能让某段重复验证步骤适合整理成脚本或 Skill。提炼之前，需要区分三类材料：

活动记录中的一次观察，经过核对后才可能形成长期知识。候选内容至少应说明来源、适用范围、验证情况、确认状态和维护位置；容易随模块或环境变化的内容，还应记录更新时间与重新核对条件。

这些信息可以写在文档或 Skill 中，也可以用 source、scope、verification、review_status、updated_at 等字段组织。字段形式可以调整，关键是后续任务能够追溯结论，判断它是否仍然适用。

Agent 可以协助发现、提炼和起草，使用者负责核对证据与适用范围，并决定是否更新。确认过的内容提交到相应维护位置，更新长期 Workspace 中的内容或引用，形成后续版本；证据不足或来源冲突的内容继续标为待确认，避免成为后续任务的稳定依据。

例如，确认过的字段兼容约定可以补入项目知识，重复的构建操作可以整理成脚本，本次环境偶发故障则保留发生条件和诊断结果。代码交付已经通过，也需要单独判断这些候选内容是否适合长期复用。

九、渐进建设与效果验证

按真实任务逐步建设

起步可以选择一个持续参与的项目，列出自己反复向 Agent 解释的 3 到 5 个问题：仓库在哪里、业务约定去哪里查、如何构建、怎样验证、哪些动作需要确认。先让一个新 Session 基于现有材料尝试完成这些准备，再补充找不到的资料、不可用的工具和含糊的要求。

从准备项目到交付并复用经验，可以按 L1–L3 三个阶段逐步建设。这是本文采用的实践划分，各阶段用真实任务验收：

• L1：能够进入项目。 建立项目说明、仓库地图、修改边界、启动方法和一个基础验证入口。用新 Session 检查它能否找到正确仓库、准备环境并跑通基础检查，记录还需要人补充什么。
• L2：能够完成研发微循环。 在 L1 上补充高频 Skill、可执行脚本、测试入口与评审方法。选择一项边界清楚的需求，在任务现场走完实现、测试、修复和评审，保留当时使用的长期版本与执行结果。
• L3：交付有证据，经验能够复用。 补充实际环境中的验收、结构化报告、候选经验确认和版本更新。任务结束后归档，再用下一项同类任务检查已确认的经验能否被找到并正确使用。

每个阶段都应有独立价值，可以停留在满足当前工作需要的程度。

沿高频流程补充能力

建设顺序可以由日常阻塞决定。反复补充需求边界，就先完善澄清和 Spec；代码经常写完却无法验证，就先打通环境、测试与证据；同类问题重复排查，就先完善故障索引和经验回写。

在选定的流程里，把入口规则放到 Agent 能发现的位置，把可重复执行的动作放进脚本，把需要判断和步骤组织的方法写成 Skill。阶段衔接、产物和退出条件写进工作流，需要自动触发检查时，再按客户端支持的事件接入 Hook。

用任务结果检验效果

文档数、Skill 数和调用次数可以记录建设活动，是否值得继续投入还要看任务结果。个人实践可以先观察几项容易记录的信号：

比较时应限定相近的任务类型，记录观察的任务数和建设前情况，避免用单次成功推断整体收益。后续任务中仍然反复需要补充的内容，就是下一轮改进的依据；相应变化通过版本历史保留下来。

相关笔记

• 从 Code Context 到 Business Context：多代码库中的 Agent 路由
• Agent Skills 完全指南
• Agent Hook 完全指南
• Agent MCP 完全指南
• Agent Plugin 完全指南
• 把需求写成可验证的 Spec
• 1. 查看当前 worktree（默认只有一个）