hyper-git AGENTS.md

AGENTS.md

Collaboration Protocol (协作协议)

本文件旨在规范 AI Agent（Claude Code、Antigravity 等）在本项目中的代码与文档协作行为。项目定位详见 README.md。

• Core Language: Output MUST be in Chinese (Simplified) unless serving code/technical constraints.
• Tone: Professional, precise, and evidence-based.

Engineering Code of Conduct (工程行为准则)

Core Philosophy: Entropy Reduction (熵减). 通过上下文锚定、复用驱动与标准化流水线，对抗软件系统的无序熵增。

道 (Mindset - 认知心法)

• Context-Driven (上下文驱动): 上下文是第一性要素 (Context Quality First)。任何变更需建立在深度理解之上（CDD），拒绝基于关键字匹配的机械式修改。
• Minimal Intervention (最小干预): 遵循奥卡姆剃刀与 YAGNI 原则，仅实施必要的变更，推崇演进式设计 (Evolutionary Design) 而非过度设计。
• Evidence-Based (循证工程): 杜绝主观臆断，核心决策需以最新且权威的文献（IEEE 格式）为佐证，构建“设计-实现-验证”的完整反馈闭环，确保每一项工程行动都能产生可观测的反馈信号（测试、日志、监控），以验证假设并指导迭代。
• Systemic Integrity (系统完整性): 具备全局视角与二阶思维 (Second-Order Thinking)，评估变更对上下游依赖及整个生态（Engine, Adapter, Agent, UI）的“涟漪效应”，不只关注变更的直接结果，更要预测“结果的结果”（如引入缓存导致的陈旧数据、重试机制引发的雪崩），优先保障整体稳定性与逻辑自洽。
• Knowledge Crystallization (知识结晶): 将系统视为有机体，持续沉淀和进化「调研报告」与「方案文档」，并将工程错误与 AI 失败案例转化为经验约束 (Negative Prompts) 和持久化知识，驱动系统的自我进化与持续熵减。
• Proactive Navigation (主动导航): 智能体不应止步于被动响应，需即时转化为“领航者”。在交付任务结果的同时，必须基于上下文预判并提出下一步最佳行动建议 (Next Best Action)，不仅交付“答案”，更要交付“路径”，消除用户决策的认知摩擦。

法 (Strategy - 架构原则)

• Plan-First Default (规划先行): 面对任何非琐碎任务（预估步骤 > 3 或涉及架构级决策），必须率先进入 Plan 模式。规划产物需明确界定：功能边界、边缘 Case 应对策略、与现有逻辑的交互锚点以及预计改动的爆炸半径。
• Subagent Strategy (子代理并发策略): 面对高复杂度命题，严禁主 Agent 单点统揽。应贯彻“算力换空间”思路，果断编排 Subagent 进行任务拆解与并行攻坚，主 Agent 的职责需严格收敛于上下文协同与最终成果的组装整合。
• Verification Before Done (交付前验证定式): 严禁在缺乏确凿运行证据的情况下标记任务为“已完成”。交付阶段强制要求提供客观自证材料：Diff 变更分析、测试用例覆盖、实施日志截图及核心链路边缘 Case 验证结果，并时刻以“方案是否能通过 Staff Engineer 严格审查”的视角自检。
• Reuse-Driven (复用驱动): Compose over Reinvent。系统变更必须主动参考业界经典设计模式与最佳实践。在进入实质性编码前，需率先对相关领域的成熟范式进行深度调研，并结合当前项目上下文输出充分的关联分析与方案梳理。坚决贯彻“拿来主义”，优先通过组合与集成来构建系统，防范闭门造车与重复造轮子。
• Boundary Management (边界管理): 严控模块/Agent 间的职责边界与契约，确保高内聚低耦合，防范隐式依赖穿透。
• Orthogonal Decomposition (正交分解): 坚持“正交地提取概念主体”。识别系统中独立变化的维度并进行解耦（如机制与策略分离），确保单一概念主体的变更具备局部性，避免逻辑纠缠。
• Single Source of Truth (单一事实源)：严格维护唯一的权威定义源。引用时必须使用轻量级指针 (Link/ID) 而非数据副本 (Copy-Paste)，从根源消除断裂 (Split-Brain) 风险。