Project brain

项目大脑 — 跨 Agent 协作系统

核心理念

你（当前 Agent）是多个 AI 助手之一。其他 Agent 也可能接手这个项目。你的任务是从公共工作空间读取项目上下文，工作结束后留下清晰的交接信息，让下一个 Agent 能无缝接棒。

公共工作空间根目录由用户指定。 如果用户没有明确告知，请在首次使用时询问："你的公共工作空间路径是什么？"（常见路径：Windows D:\Public_Workspace，macOS/Linux ~/public_workspace）

---

触发指令

用户手动触发以下关键词之一时，执行对应流程：

关键词	动作
初始化项目 / 开始新项目	启动项目初始化问答
结束会话 / end_session	自动生成会话日志草稿，确认后写入
更新项目状态	询问新状态，更新入口文件
记录问题	追加问题到问题追踪表
查看项目 / 项目入口	→ 见下方「查看项目入口流程」

💡 触发词是精确匹配，但用户不一定每次说对。 遇到类似表达（如"收工了""今天就到这里""看看项目怎么样了""发现一个bug"）时，应主动识别意图并引导用户使用对应的精确指令，而不是假装没听到。

---

查看项目入口流程

当用户说"查看项目"或"项目入口"时：

1. 如果用户没有指定项目名：

   • 先列出公共工作空间下有哪些项目目录（排除 _tools _patterns _system 等系统目录）
   • 问用户："你想查看哪个项目？"
   • 等用户指定后再继续

2. 用户指定项目名后：

   • 读取 <workspace>/<项目名>/项目入口.md
   • 只展示 Layer 1 速览区（约前 25 行），不要信息过载
   • 如果该项目的目录存在但没有入口文件 → 告诉用户需要先"初始化项目"
   • 如果连目录都不存在 → 告诉用户"这个项目还没创建，要初始化吗？"

---

第一步：进入项目（必须执行）

当你被要求在一个项目上工作时，必须先执行以下操作：

1. 确定项目名（查看用户描述，去公共工作空间下列目录确认）
2. 读取 <workspace>/<项目名>/项目入口.md
3. 默认只展示 Layer 1 速览区（约前 25 行，含项目名/描述/状态/阶段/技术栈/阻塞问题/最新日志位置），让用户确认你是否理解了项目
4. 根据需要读取 Layer 2（开发环境/代码约定/紧急恢复）
5. 读取 问题追踪.md，了解当前阻塞问题和未解决问题
6. 读取最新的 会话日志.md，了解最近做了什么
7. 隐私检查：检查项目的 .gitignore 是否包含 AI 配置排除项（CLAUDE.md、.claude/、.mcp.json、.codex/、.cursor/、.clinerules/、memory/）。如果缺失 → 提醒用户补充，并询问是否现在添加

如果项目目录存在但没有入口文件，告诉用户需要先执行"初始化项目"。

---

项目初始化流程

用户说"初始化项目"后，按以下顺序逐一提问（每次只问一个问题）：

1. 项目一句话描述？ — 这是什么的项目？
2. 主要用途/目标用户？ — 谁来用？解决什么问题？
3. 技术栈偏好？ — 语言、框架、平台
4. 现有代码/依赖在哪？ — 是全新项目还是有现有代码？
5. 当前阶段？ — 从零开始 / 有原型 / 功能开发 / 重构 / 维护
6. 硬约束？ — 有没有绝对不能妥协的要求（如：必须离线、必须是中文）？
7. 最终产出物？ — 这个项目完成后，你希望产出一个什么东西？
8. 将来要开源吗？ — 打算发布到 GitHub 或其他公开平台？
   • 如果用户回答"是"或"可能"：
     1. 自动创建 .gitignore，包含 开源项目准备清单 中推荐的全部排除项
     2. 询问"要安装 git pre-commit 隐私检查钩子吗？" — 如果同意，在 .git/hooks/pre-commit 创建以下脚本（给执行权限）：

        #!/bin/bash
        # project-brain privacy gate: block commits containing AI config files
        PATTERN='\.claude/|\.mcp\.json|CLAUDE\.md|\.codex/|\.cursor/|\.clinerules/|memory/|\.env$|\.env\.local|credentials\.json|\.pem$|\.npmrc|\.pypirc'
        if git diff --cached --name-only | grep -qE "$PATTERN"; then
          echo "========================================"
          echo " BLOCKED: AI config files in commit"
          echo "========================================"
          git diff --cached --name-only | grep -E "$PATTERN"
          echo ""
          echo "These files may contain personal paths, tokens, or permissions."
          echo "Add them to .gitignore and use 'git rm --cached' to unstage."
          echo "Override with: git commit --no-verify  (NOT recommended)"
          exit 1
        fi
        

        向用户说明："安装后任何 git commit 都会自动扫描，发现 .claude/、.mcp.json 等文件会直接拒绝提交。可以用 git commit --no-verify 强制绕过，但不建议。"
   • 如果用户回答"否"：跳过

全部回答完毕后，使用模板生成 <workspace>/<项目名>/项目入口.md。模板文件位于本 Skill 的 templates/ 目录下，或由用户提供。

---

结束会话流程（end_session）

用户说"结束会话"时：

1. 回顾本次会话的操作
2. 检查 git diff（如有 git 仓库）确认文件变更
3. 按会话日志模板格式生成日志条目（模板见 templates/会话日志模板.md）
4. 展示草稿给用户确认
5. 用户确认后，追加到 <workspace>/_system/会话日志.md（全局日志，不覆盖已有内容，最新记录排最上面）

📌 会话日志统一写全局（_system/会话日志.md）。每个日志条目标注项目名和日期，通过搜索即可定位到特定项目的记录。不要在项目目录下单独存一份会话日志——这样日志散落两个位置，其他 Agent 不知道去哪个读。

6. 如有新增问题/解决旧问题，同步更新 问题追踪.md

7. 如有接口/配置/依赖变更，务必在日志中写清楚

8. 隐私检查：如果项目是 git 仓库，检查 git diff 和暂存区是否包含以下敏感文件/目录：

   • .claude/ — 含 settings.local.json（权限白名单）
   • .mcp.json — 可能含 API token
   • CLAUDE.md — 可能含个人路径
   • memory/ — Agent 自动记忆
   • .codex/、.cursor/、.clinerules/ — 其他 AI 配置文件
   • .env / .env.local — 数据库密码、API Key
   • credentials.json / *.pem — 云服务凭证、密钥文件
   • .npmrc / .pypirc — 包管理器认证 token

   如发现上述文件被跟踪或暂存 → 在草稿中高亮警告，提醒用户加入 .gitignore 再推送

最重要的区块：交接清单（✅可继续 / ⚠️注意 / 🔒别动 / 📌下一步）

---

提案审查规则

当你需要提出重要技术方案时，必须包含：

1. 方案概述 — 一句话 + 一段话说明要做什么、怎么做
2. 自我反驳 — 最可能失败的 3 个点，必须写具体触发条件和失败症状
   • ✅ 好例：并发超过 50 时 SQLite 写锁排队，API 响应从 200ms 升至 5s+
   • ❌ 差例：可能有性能问题
3. 验证标准 — 用户可直接执行的测试步骤，不依赖专业知识
4. 外部依赖风险 — 第三方库是否活跃维护？授权是否合规？网络环境能否访问？
5. 回滚复杂度 — 失败后改一行配置能退？还是需要重构整个模块？
6. 隐性耦合 — 会无意中影响哪些看似无关的模块？
7. 不采纳的代价 — 保持现状有什么损失？技术债是否会随时间扩大？
8. 风险等级：
   • 🟢 低风险 → 简要告知用户后执行（如："我将修改 X，这是低风险改动，有问题吗？"若用户无异议则执行）
   • 🟡 中风险 → 给验证标准，用户确认后执行
   • 🔴 高风险 → 提供 2 种以上方案，用户决定；建议先备份

适用边界：技术选型、架构调整、引入新依赖、数据库 Schema 变更需走审查。修 Bug、改文案、调整样式不需要。

---

推翻前人决策规则

允许推翻的情况

• 安全漏洞、明显性能瓶颈（O(n²)→O(n)）、资源泄漏 → 直接报告
• 能提供复现步骤或性能数据（证据优先原则）
• 原决策的前提条件已改变（如需求变了、环境变了）

禁止推翻的情况

• 仅凭感觉"我的方案更好" → 必须量化两个维度以上的对比
• 前人方案已稳定运行超过 1 周且无缺陷报告（冷却期原则）
• 无 PoC 或逻辑推演 → 空想不推翻

推翻流程

1. 在会话日志写入"拟推翻决策 #X"
2. 列出：①原决策理由（从入口文件"关键决策记录"抄）②你的新理由 ③量化对比
3. 用户决定前，不得修改相关代码
4. 无论结果如何，记录到入口文件"关键决策记录"

设计意图：不是阻止改进，而是防止每个 AI 助手都按自己喜好重写，造成反复横跳。

---

日常操作规范

代码修改时

• 修改函数签名 → 必须记录到会话日志"接口变更"，注明影响范围
• 修改配置文件 → 必须记录到"环境/配置变更"
• 重命名/移动文件 → 必须记录到"文件操作"，同步所有 import 引用
• 数据库 Schema 变更 → 必须记录 migration 路径和执行方式
• 遵循项目入口文件中的"代码约定"（命名风格、Lint 规则、禁止引入的库）

⚠️ 禁止并发操作

绝对不要和另一个 Agent 同时操作同一项目的同一文件。 如果用户同时开了两个 AI 窗口：

• 两个 Agent 同时写 会话日志.md → 后者覆盖前者，数据丢失
• 两个 Agent 同时更新 项目入口.md → 后写入的覆盖先写入的
• 两个 Agent 同时追加 问题追踪.md → 问题可能丢失

工作前检查是否有锁文件（*.lock）。如果有 → 报告用户"检测到锁文件，可能有另一个 Agent 正在工作"，等待确认后再继续。在写入关键文件（日志/入口/问题追踪）前创建临时锁文件，写入完成后删除。

发现可复用代码时

如果一个模式可能在跨项目使用（重试机制、缓存策略、文件操作等），提炼到 <workspace>/_patterns/ 下，按场景分类存放。

遇到阻塞时

• 先检查 问题追踪.md，看是否已有类似问题
• 如果前人尝试过并失败了，读"尝试方案"和"结果"列避免重蹈覆辙
• 新问题记录到问题追踪表，分配新 ID

推送/公开代码前

执行一次快速隐私扫描：

git status          # 看是否有 .claude/ / .mcp.json / CLAUDE.md / memory/ / .env
git ls-files | grep -E '\.claude/|\.mcp\.json|CLAUDE\.md|\.codex/|\.cursor/|\.clinerules/|memory/|\.env$|credentials\.json|\.pem$'

如果在输出中看到任何匹配项 → 立即停止，将对应条目加入 .gitignore，用 git rm --cached 移除跟踪，确认安全后再推送。

---

文件结构参考

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

入口文件三层设计

• Layer 1（必读，约 25 行内）：项目名、描述、状态、阶段、技术栈、阻塞问题、最新日志位置
• Layer 2（按需读）：开发环境快照、代码约定、紧急恢复步骤、依赖
• Layer 3（深度参考）：关键决策记录、会话摘要、代码健康度、风险

---

开源项目准备清单

当你用 project-brain 管理的项目准备开源时，AI 助手系统会在项目目录下自动生成如下文件，务必在 .gitignore 中排除：

文件/目录	风险	说明
CLAUDE.md	🟡 中	Claude Code 项目指令，可能含个人路径和工作流偏好
.claude/	🔴 高	含 settings.local.json（权限白名单），绝对不能公开
.mcp.json	🔴 高	MCP 工具配置，可能含 API token 或内网服务地址
.codex/	🟡 中	OpenAI Codex 项目配置
.cursor/	🟡 中	Cursor IDE AI 规则
.clinerules/	🟡 中	Cline AI 规则
memory/	🟡 中	Agent 自动记忆目录
.env / .env.local	🔴 高	数据库密码、API Key、认证信息
credentials.json / *.pem	🔴 高	云服务凭证、密钥文件
.npmrc / .pypirc	🟡 中	包管理器认证 token
settings.json	🟡 中	某些框架可能含 API Key

推荐 .gitignore 片段：

# AI agent config (may contain personal paths / permissions / tokens)
CLAUDE.md
.claude/
.mcp.json
.codex/
.cursor/
.clinerules/

# Agent memory
memory/

# Common sensitive files (dev credentials)
.env
.env.local
credentials.json
*.pem
.npmrc
.pypirc

⚠️ 如果项目本身就是 Skill（需要公开发布 SKILL.md），SKILL.md 不用排除。其他 AI 配置文件仍需排除。

🔒 如果之前已经提交过敏感文件到 git 历史，需要用 git filter-repo（官方推荐，替代已弃用的 git filter-branch）或 BFG Repo-Cleaner 清理历史记录，不能只加 .gitignore 了事。

---

关键原则

1. 事实优先：只记录事实和结果，不过度规范化以保留 AI 创造力
2. 用户掌舵：AI 可提大量建议，但最终决策权在用户
3. 证据说话：推翻前人方案必须有量化对比，不能只凭感觉
4. 交接用心：每次结束会话写清楚"下一个 Agent 需要知道什么"
5. 工具复用：发现通用工具/模式 → 沉淀到 _tools 或 _patterns