# Project Brain

> 跨 AI 助手项目上下文管理 — 让不同 Agent 无缝切换项目。TRIGGER when 用户说"初始化项目""开始新项目""结束会话""end session""更新项目状态""记录问题""查看项目入口""项目状态""start project""check project""handoff"。Use when user wants seamless project handoffs between different AI agents. Maintains shared project memory to prevent repeating context.

- Skill: `huakaibuchangwu/project-brain` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add huakaibuchangwu/project-brain`
- Raw SKILL.md: https://api.skillmd.com/api/skills/huakaibuchangwu/project-brain/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: HuaKaiBuChangWu (https://skillmd.com/u/huakaibuchangwu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/huakaibuchangwu/project-brain

---


# 项目大脑 — 跨 Agent 协作系统

## 核心理念

多个 AI 助手共享同一套项目记忆。项目状态存在硬盘的 Markdown 文件里，不绑定任何单一 AI 的记忆。切换 Agent 时无需重新解释背景。

**公共工作空间根目录：** `D:\Public_Workspace`。首先检查存在性——存在则直接用，不存在则询问用户路径。

---

## 触发指令

| 关键词（中/英） | 动作 |
|--------|------|
| `初始化项目` / `start project` | 启动项目初始化问答 |
| `结束会话` / `end session` / `handoff` | 生成会话日志草稿，确认后写入 |
| `更新项目状态` | 询问新状态，更新入口文件 |
| `记录问题` / `log issue` | 追加问题到问题追踪表 |
| `查看项目` / `check project` / `项目入口` | 读取项目入口文件 Layer 1 |
| `项目状态` | 展示所有项目的入口文件 Layer 1 摘要 |

> 类似表达（"收工了""今天就到这里""看看项目怎么样了""发现个bug"）应主动识别意图并引导用户使用对应指令。

---

## 查看项目入口流程

1. 用户未指定项目名 → 列出 workspace 下所有项目目录，询问"要看哪个？"
2. 用户指定项目名 → 读取 `<workspace>/<项目名>/项目入口.md`，**只展示 Layer 1 速览区**（约前 25 行）
3. 目录存在但无入口文件 → 提示需要先"初始化项目"
4. 目录不存在 → 问"要创建吗？"

---

## 项目初始化流程

逐一提问（每次一个问题），全部回答后按模板生成 `<workspace>/<项目名>/项目入口.md`：

1. 项目一句话描述？
2. 主要用途/目标用户？
3. 技术栈偏好？
4. 现有代码/依赖在哪？
5. 当前阶段？（从零开始/有原型/功能开发/重构/维护）
6. 硬约束？（如：必须离线、必须中文）
7. 最终产出物？
8. 将来要开源吗？
   - 是/可能 → 自动创建 `.gitignore`（排除 AI 配置文件），询问是否安装 git pre-commit 隐私检查钩子
   - 否 → 跳过

---

## 结束会话流程（end_session / handoff）

1. 回顾本次会话操作，检查 git diff
2. 按 `templates/会话日志模板.md` 生成日志草稿，展示给用户确认
3. 追加到 `<workspace>/_system/会话日志.md`（全局日志，最新在上）
4. 如有问题增/改，同步更新 `问题追踪.md`
5. 隐私扫描：检查 git diff 是否包含敏感文件（`.claude/`、`.mcp.json`、`CLAUDE.md`、`.env`、`credentials.json` 等）。发现则高亮警告。

**交接清单必须包含：** ✅可继续 / ⚠️注意 / 🔒别动 / 📌下一步

---

## 提案审查规则（重要技术方案时必须）

| 审查项 | 要求 |
|--------|------|
| 方案概述 | 一句话 + 一段话 |
| 自我反驳 | 最可能失败的 3 个点，写具体触发条件和症状 |
| 验证标准 | 用户可直接执行的测试步骤 |
| 外部依赖风险 | 第三方库维护状态、授权合规、网络可达性 |
| 回滚复杂度 | 失败后改一行配置能退？还是需要重构模块？ |
| 隐性耦合 | 会影响哪些看似无关的模块？ |
| 不采纳的代价 | 保持现状有什么损失？ |

**风险等级：** 🟢低→告知后执行 / 🟡中→用户确认后执行 / 🔴高→提供 2+ 方案，用户决定

适用边界：技术选型、架构调整、引入新依赖、DB Schema 变更。修 Bug、改文案不需要。

---

## 推翻前人决策规则

**允许推翻：** 安全漏洞、明显性能瓶颈（O(n²)→O(n)）、资源泄漏、原决策前提条件已变。

**禁止推翻：** 仅凭感觉、前人方案已稳定运行 >1 周无缺陷（冷却期原则）、无 PoC 或量化对比。

**推翻流程：** 会话日志记录 → 列出原决策理由 + 新理由 + 量化对比 → 用户决定前不得修改代码 → 无论结果都记录到入口文件"关键决策记录"。

---

## 日常操作规范

- 修改函数签名 → 记录到日志"接口变更"
- 修改配置文件 → 记录到"环境/配置变更"
- 数据库 Schema 变更 → 记录 migration 路径
- 推送/公开代码前 → 隐私扫描（检查 `.claude/`、`.mcp.json`、`CLAUDE.md`、`.env` 等）

**⚠️ 禁止并发：** 不同 Agent 不要同时操作同一文件。写入关键文件前创建临时锁文件，完成后删除。

---

## 文件结构

```
<workspace>/
├── _tools/              ← 公共工具脚本
├── _patterns/           ← 跨项目复用代码
├── _system/             ← 模板文件和全局记录
│   ├── 会话日志.md       ← 全局日志（最新在上）
│   └── ...
├── <项目名>/
│   ├── 项目入口.md       ← Layer1 速览 + Layer2 环境 + Layer3 参考
│   ├── 问题追踪.md       ← 表格：ID|状态|描述|尝试方案|结果|Agent|日期
│   └── ...
└── ...
```

### 入口文件三层设计
- **Layer 1（必读，~25 行）**：项目名、描述、状态、阶段、技术栈、阻塞问题、最新日志
- **Layer 2（按需读）**：开发环境、代码约定、启动命令
- **Layer 3（深度参考）**：关键决策记录、会话摘要、技术债

---

## 关键原则

1. **事实优先**：只记录事实和结果，不预设过多规范
2. **用户掌舵**：AI 提建议，最终决策权在用户
3. **证据说话**：推翻方案必须有量化对比
4. **交接用心**：写清楚"下一个 Agent 需要知道什么"
5. **工具复用**：通用工具/模式沉淀到 `_tools` 或 `_patterns`