Agent Workspace Reference Architecture

面向多项目 Coding Agent 的 Git-native 上下文控制平面。

它把项目地图、执行约束、会话交接、长期经验和轻量自动化放回 Git 仓库，让 Codex、Claude Code、Cursor 等工具共享一套可审查的工作区上下文，而不是把关键知识锁进某个 Agent 的私有记忆。

当前状态

仓库正在开发 2.0.0-alpha.0，alpha 尚未发布到 npm；npm 上的 create-agent-workspace@1.1.0 仍是上一代实现。v2 目前适合试用、评审和提供反馈，不建议直接作为无人值守的生产自动化。

• 运行时：Node.js 22+
• 平台：Linux、macOS
• 依赖：核心 CLI 零运行时 npm 依赖
• 安全默认值：已有文件一律保留；路径或类型冲突时，在写入前停止

为什么做这个项目

Coding Agent 真正难维护的通常不是 prompt，而是跨仓库、跨 session 的上下文：入口散落、交接过期、规则互相冲突、自动化悄悄覆盖人工内容。

这个参考架构采用三个简单边界：

1. AGENTS.md 描述稳定规则与项目地图。
2. HANDOVER.md 描述下一位 Agent 可以继续的当前状态。
3. LEARNINGS.md 与 ADR 保存经过人工判断、长期有效的经验和决策。

所有内容都是普通文件，可以 review、diff、回滚和迁移；不要求数据库、常驻服务或特定模型供应商。

本地试用 v2 alpha

git clone https://github.com/lennney/agent-workspace-refarch.git
cd agent-workspace-refarch
npm ci

# 初始化一个含两个项目的工作区
node bin/cli.js init ../my-workspace api web --type node --hooks --ci

旧脚本仍可使用，并转发到同一份 Node CLI：

INSTALL_HOOKS=y bash setup.sh ../my-workspace api web --type node

CLI 也兼容 v1 的省略 init 形式：

node bin/cli.js ../my-workspace api web --hooks

再次执行是幂等的。内容相同的文件会跳过，已有且不同的文件会保留并报告；CLI 不会自动替换已有的 CLAUDE.md。

生成的结构

my-workspace/
├── AGENTS.md                 # 工作区地图与跨项目规则
├── CLAUDE.md -> AGENTS.md    # 仅在路径不存在时创建
├── .workspace.yaml
├── shared/                   # 跨项目契约和架构概览
├── api/
│   ├── AGENTS.md             # 项目命令、约束和边界
│   ├── HANDOVER.md           # 当前可恢复状态
│   ├── LEARNINGS.md          # 人工确认的长期经验
│   └── docs/                 # 计划、ADR、排错与索引
└── web/

可选的 --hooks 安装五个 Claude Code 生命周期 hook：

Hook	Phase 0 行为
SessionStart	只读检查 AGENTS、HANDOVER 和 CLAUDE 状态
PreToolUse	从 stdin 读取待修改路径并给出影响分析提示
PostToolUse	在项目根记录最近编辑路径
PreCompact	保存 staged、unstaged、untracked 文件的恢复快照
SessionEnd	向现有 HANDOVER 追加轻量 session 记录

--ci 会安装固定版本的 agents-lint 工作流。项目不会自动安装 pre-commit，也不会自动归档或自动晋升长期记忆。

适合谁

• 同时维护多个相互依赖仓库的个人开发者或小团队
• 在多个 Coding Agent 之间切换、希望规则可迁移的团队
• 想先采用文件和 Git，而不想部署完整 Agent 平台的项目
• 正在建立 AI-assisted development 治理基线的开源仓库

如果只有一个很小的仓库，先用一份 AGENTS.md 加一份短 HANDOVER.md 就够了；不必把整套结构全部装上。

与其他实践的关系

• 遵循 AGENTS.md 的渐进式目录上下文，而不是发明私有规则格式。
• 借鉴 Coding Agent 的分层记忆实践，但把候选经验的人工晋升留到 Phase 1。
• 借鉴规格驱动开发的版本与验证纪律，同时保持运行时无服务、低依赖。

这里的差异化不是“另一个 Agent 框架”，而是给现有 Agent 提供一个可审查、可恢复、跨工具的上下文底座。

路线图

• Phase 0：唯一 CLI、安全初始化、hooks 修复、打包测试与 CI（进行中）
• Phase 1：候选记忆 → 人工晋升，HANDOVER 从日志改为当前状态
• Phase 2：plan / doctor / upgrade 与迁移报告
• Phase 3：上下文收敛、适配器和可观测指标

详细需求与设计见 docs/requirements/、docs/superpowers/specs/ 和 docs/plans/。

参与贡献

欢迎优先反馈三类问题：初始化是否保留了已有内容、跨 session 是否真的更容易恢复、生成的上下文是否足够短且准确。提交前请运行：

npm ci
npm test
npm pack --dry-run

发布 npm、创建 tag 或 GitHub Release 不属于当前 Phase 0 自动流程。