AI Common

外观

Vibe Coding 核心协作协议 ​

🛡️ 0. 协议优先与隐私原则 (Protocol First & Privacy) ​

这是最高优先级规则，任何操作不得违背。

  1. 动作前检索 (Pre-Action Lookup)： 在执行具有特定业务属性的任务（如写文章、操作数据库、发布版本、生成组件）前，必须先检索 docs/skills/ 目录下是否存在对应的 Skill 定义。

    • 命中协议：必须严格遵守该 Skill 定义的 Save Path（保存路径）、Output Format（格式）和 Privacy（隐私规则）。
    • 未命中：按通用 Vibe Coding 流程执行。

  2. 默认私有 (Default to Private)：

    • 非代码资产（如文章草稿、复盘日志、数据库切片配置）默认视为私有。
    • 严禁：在没有 Skill 明确授权或用户显式指令的情况下，将此类文件 git push 到公开仓库。
    • 例外：明确标记为 Public 的文档（如 index.md, tech_stack.md）除外。

🕵️ 1. 引用透明化标准 (Source Transparency) ​

为了明确“显式规则”与“隐式检索”的边界，回复必须包含来源标记：

  • 当读取本地文件时 (Explicit)： 若回复主要依据 read_file 的内容，需在段落前标记：[📂 规则: xxx.md]

  • 当使用知识库检索时 (Implicit)： 若回复引用了 searchKnowledgeBase 的结果（向量检索），需在段落前标记：[🧠 RAG] 或 [🧠 历史复盘]

  • 优先级冲突处理： 若 [📂] 与 [🧠] 内容冲突，以 [📂 本地文件] (Explicit) 为准（视为最新项目规范）。

核心流程 (The 4-Step Loop) ​

  1. 代码编写 (Coding)：Codex 根据需求快速生成功能原型。
  2. 错误积累 (Accumulation)：在本地运行，收集报错日志或逻辑异常。
  3. 结果验证 (Verification)：将代码与报错发给 Gemini 进行深度因果分析。
  4. 修改计划 (Planning)：Gemini 制定修复方案，Codex 执行精准修改。

关键细化规则 (Operational Rules) ​

  • 环境探测清单：先确认项目根目录（package.json/pnpm-lock.yaml/yarn.lock/package-lock.json/.git 之一存在）；至少检查 package.json、tsconfig.json、构建配置（如 vite.config.*/next.config.*）与入口文件结构。
  • 错误日志标准：必须包含“执行命令 + 完整报错栈 + 相关配置片段 + 复现步骤/输入条件”，否则视为未完成 Accumulation。
  • 复杂问题定义：满足任一条件即需记录 retrospective.md：影响范围超过 1 个模块、修复耗时 > 30 分钟、涉及构建/运行时/依赖冲突交叉问题、连续两次试错仍无效。
  • 交接点：连续两次尝试无果或错误原因不明确时，必须进入 Verification，不得继续盲改。
  • 改动安全标准：改动前先确认现有行为与复现方式；改动后给出验证步骤（测试/运行命令或手动检查路径）。
  • 技能包移除校验：执行移除技能包后，必须检查移除结果（目录是否不存在或技能列表已更新）。
  • 重构验收流程：重构/优化任务完成后，必须执行构建或测试命令，并打开页面进行人工验收，确认功能与样式正常。
  • 前端清理规范：关注 index.html 的 logo/静态资源加载；删除遗留代码与弃用组件，清理无用依赖与资源，避免屎山堆积与死代码残留。
  • 纯函数工具包：关注复杂度与兼容性；可使用高阶技巧但必须配清晰注释，避免引入不必要的依赖导致可读性下降。
  • 技术栈切换规则：以项目真实配置为准；检测到 React/Next/Node CLI 等即切换对应范式与脚手架习惯，默认 Vue 仅用于新建项目。
  • 输出格式要求：回复需包含“改动路径 + 变更原因 + 验证建议”；若无法验证需说明原因。
  • AI 需求文档要求：每个项目根目录必须新增一份 AI 需求文档（Markdown），记录本次同步改了哪些功能；该文档只能追加内容，不允许修改或删除既有记录。
  • 入口 SEO 与 Logo 一致性：index.html 必须考虑 SEO（如标题、描述等基础标签），并确保标签页 favicon 与站内 logo 高度统一；若项目没有 logo，则生成一个 SVG 作为统一标识。

输出模板 (Templates) ​

  • Accumulation 日志：
命令:
现象:
完整报错:
复现步骤:
相关配置:
  • 最终回复：
改动路径:
变更原因:
验证建议:

协作准则 ​

  • 分析优先：严禁在未分析根因前盲目重写代码。
  • 规则进化：每次重大修复后，需评估是否需要更新本规则或 retrospective.md。
  • 环境适配：所有产出必须适配 Mac (macOS) 本地开发环境。

Skill 维护与跨目录操作 (Skill Maintenance) ​

  • 跨目录读取能力: AI 不受当前项目工作目录限制。在必要时（如修改全局规则、维护 Skill） ，必须主动通过 Shell 命令访问 ~/.gemini/ 或 ~/Documents/AI_Common/。

  • Skill 源码优先: 当需要调整 AI 的技能行为（如撰写风格、代码审查逻辑）时，必须直接修改 .gemini/skills/ 下对应的 GEMINI.md 源码，而不是通过临时的 Patch 文件进行“外挂式” 修补。

🧬 2. 互动与环境规则 (Interaction & Environment Rules) ​

  1. 项目打开偏好 (Project Opening)： 默认使用 Zed 打开项目，不再询问其他编辑器；仅当用户明确要求时再切换。

  2. 外部记忆同步 (Memory Sync)： 所有关于项目索引、用户偏好或长期规则的改动，必须同步至 ~/Documents/AI_Common/ 目录下，以实现跨项目知识共享。