Cyber-AI-Forge: Instructions file for Codex

AI 协作规则

本文件适用于整个仓库。任何 AI Agent 在修改项目时都必须遵守这些规则。

人类修改优先与冲突处理

1. 人类维护者写入或确认的代码、配置、测试、文档和明确指令，是判断当前项目意图的首要事实来源。AI 的既有实现、聊天推断、历史设计和归档记录不得覆盖人类修改。
2. AI 可以审阅人类修改，但未经人类明确授权，不得以修复、重构、同步、规范化或恢复旧设计为由改写、回退、删除或重命名这些内容。人类明确授权的机械操作（例如仓库格式化）只在授权范围内执行。
3. 开始任务时发现的既有未提交改动一律视为人类内容。AI 必须避开这些改动；无法隔离时停止并询问人类，不得自行判断所有权。
4. 当实现与测试、现行文档、ADR 或历史记录冲突时，先以人类实现描述当前事实，不得用旧文档反向修改实现。若用户已明确要求同步文档，可以修正含义明确的失配；若发现 bug、风险、行为意图不明或任务范围外的未同步文档，必须说明证据和影响并询问人类下一步，不得静默修复或猜测。
5. 人类确认的长期结论必须同步到现行设计或 ADR；AI 协作记录和归档内容不能代替当前规范。

Git 安全门禁与 AI 提交标记

开始修改前的暂存区硬门禁

1. 每次 AI 执行任何可能修改代码或仓库文件的任务时，必须在首次修改文件前执行 git diff --cached --quiet，确认当前仓库相对 HEAD 没有任何已暂存内容。该检查优先于阅读文档和实施任务。
2. 如果命令因存在已暂存差异而返回非零状态，AI 必须立即停止，不得修改任何文件，并明确要求人类先提交这些已暂存内容。只有人类完成提交后，AI 重新检查并确认暂存区为空，才能开始工作。
3. AI 不得通过代替人类提交既有暂存内容、取消暂存、还原、删除或其他方式绕过门禁。无法确认暂存内容是否属于当前 AI 任务时，一律视为人类既有内容并停止。
4. 该门禁检查针对任务开始时的既有暂存内容。AI 完成本轮修改和验证后，可以暂存本轮改动以创建自动提交。

AI 自动提交的强制标记

1. AI 创建的每一个 Git 提交，都必须在提交消息末尾追加以下 trailer，并将模型名称替换为执行该提交的真实 AI 模型名称：

   Co-Authored-By: -AI- [AI model name] <[email protected]>
   

2. [AI model name] 只是格式占位符，禁止原样写入提交；也不得填写无法确认的简称、产品名或虚构名称。当前执行模型名称不明确时，AI 必须停止提交并说明阻塞。

3. trailer 与提交正文之间必须保留一个空行。即使提交仅包含文档、配置、测试或其他非业务代码改动，也必须保留该标记。

4. 创建提交后，AI 必须使用 git log -1 --format=full 或等价命令验证 trailer 已正确写入；缺失或错误时不得宣称任务完成。

开始工作前

1. 阅读 docs/README.md 并判断任务属于 foundation、forge 或 platform。
2. 按 docs/README.md 的最小阅读协议，只阅读对应作用域中与改动直接相关的 design/ 文档和仍有效的 decisions/ 记录；禁止为建立背景而递归读取整个 docs/。
3. 检查对应 docs/<scope>/plans/active/ 中是否已有同一事项的实施计划，避免重复规划。
4. 各作用域的 archive/** 默认不得读取。只有用户明确要求历史、当前文档明确引用历史证据、排查回归/兼容性或准备恢复旧方案时，才先读对应 archive/README.md 并选择最相关的一至两份文件。
5. 不得仅凭聊天上下文推断长期约定；长期有效的结论必须写入仓库文档。

代码格式

• 仓库根目录 .prettierrc.json 是 JavaScript、TypeScript、Vue、JSON、Markdown 和样式文件的 唯一格式来源；AI 生成代码时必须直接遵守该配置，不得从个人编辑器设置推断额外规则。
• 完成代码修改后执行 pnpm format，并在最终验证中执行 pnpm format:check。
• pre-commit hook 只负责格式化已暂存文件，不能代替测试、构建或 AI 对最终 diff 的检查。

前端验证边界

• apps/frontend 不维护单元、组件或端到端自动化测试；前端功能和浏览器行为由人类维护者人工验收。
• 除非用户在具体任务中明确要求，AI 不得创建或运行前端自动化测试或浏览器测试。
• AI 可以执行前端格式检查、TypeScript 检查和生产构建，但必须明确这些检查不代替人工功能验收。
• 后端、共享契约和数据库的测试与验证规则不受此前端边界影响。