agent-native-architecture

Agent 原生架构

工作规则

• 将权限、范围、审批和运行时隔离交由可信的编排机制管理；仅靠提示词无法强制执行这些要求。
• 提供明确的完成和部分进度信号、持久状态，以及可观测的操作结果。
• 使用真实任务验证能力，包括失败和中断路径；不要根据使用时长推断能力有所提升。
• 根据原始输入评估发现效果。 重放固定候选项只能衡量分类能力，无法发现搜索方式变化后会遗漏或凭空生成的候选项。将每种发现方案与同一组完整输入上的全新基线进行隔离比较。独立审核完整结果集中的未匹配输出，包括来自干净任务的输出。
• 按模型校准决策门槛。 替换模型的置信度分数无法沿用旧模型的截断值，即使排序准确率有所提高。使用单独的校准集拟合阈值。通过生产决策路径，在未经处理且具有代表性的案例上验证假阳性和假阴性表现。
• 使用所选主题的参考资料和架构检查清单，制定有依据且具体的设计，并明确尚未解决的约束。

核心原则

五项原则指导 Agent 原生设计。如需详细说明、示例和测试标准，请参阅 core-principles.md。

原则	一句话检验
一致性	Agent 能实现 UI 所允许的每一种结果吗？
粒度	更改行为只需编辑文字说明，而不必重构代码吗？
可组合性	无需编写新代码，只需编写新的提示词就能添加功能吗？
涌现能力	Agent 能处理设计之初未预料到的开放式请求吗？
随时间改进	即使不更改代码，应用一个月后也会变得更好用吗？

选择重点领域

1. 设计架构 - 从头规划新的 Agent 原生系统
2. 文件与工作区 - 将文件用作通用接口，采用共享工作区模式
3. 工具设计 - 构建基础工具、动态能力发现机制，并确保 CRUD 完整性
4. 领域工具 - 判断何时添加领域工具，何时继续使用基础工具
5. 执行模式 - 完成信号、部分完成、上下文限制
6. 系统提示词 - 在提示词中定义 Agent 行为和判断标准
7. 上下文注入 - 将应用运行时状态注入 Agent 提示词
8. 操作一致性 - 确保 Agent 能完成用户可执行的所有操作
9. 自我修改 - 让 Agent 能够安全地自我演进
10. 产品设计 - 渐进式信息披露、潜在需求、审批模式
11. 移动端模式 - iOS 存储、后台执行、检查点与恢复
12. 测试 - 测试 Agent 原生应用的能力和一致性
13. 重构 - 让现有代码更符合 Agent 原生设计
14. 反模式 - 常见错误及其规避方法
15. 成功标准 - 验证架构是否为 Agent 原生
16. Hook 模式 - Hook 事件、决策控制、MCP 匹配器、异步 Hook
17. CLI 接口 - 设计供 Agent 调用的 CLI：输出通道、退出代码、自我描述、安全级别
18. 审批闭环 - 对 Agent 起草的外部发送内容进行持久化人工审批：内容绑定、唯一胜出者声明、结果未知时的处理

当请求或委派任务明确指出主题时，直接进入对应主题。当仍有重要重点尚未确定时，在 Claude Code 中使用 AskUserQuestion 呈现相关选项（如有需要，使用 ToolSearch 加载该工具）；在 Codex 中使用 request_user_input；如果没有可用的提问工具，则在聊天中列出编号选项。只等待解决该选择所需的回答。

参考路由

响应	操作
1, "design", "architecture", "plan"	阅读 architecture-patterns.md，然后应用 architecture-review-checklist.md
2, "files", "workspace", "filesystem"	阅读 files-universal-interface.md 和 shared-workspace-architecture.md
3, "tool", "mcp", "primitive", "crud"	阅读 mcp-tool-design.md
4, "domain tool", "when to add"	阅读 from-primitives-to-domain-tools.md
5, "execution", "completion", "loop"	阅读 agent-execution-patterns.md
6, "prompt", "system prompt", "behavior"	阅读 system-prompt-design.md
7, "context", "inject", "runtime", "dynamic"	阅读 dynamic-context-injection.md
8, "parity", "ui action", "capability map"	阅读 action-parity-discipline.md
9, "self-modify", "evolve", "git"	阅读 self-modification.md
10, "product", "progressive", "approval", "latent demand"	阅读 product-implications.md
11, "mobile", "ios", "android", "background", "checkpoint"	阅读 mobile-patterns.md
11a, "icloud", "storage", "documents", "file state", "entitlement"	阅读 mobile-storage.md
11b, "background task", "battery", "on-device", "cloud routing"	阅读 mobile-execution.md
11c, "model tier", "token budget", "cost-aware", "batch", "caching"	阅读 mobile-cost.md
12, "test", "testing", "verify", "validate"	阅读 agent-native-testing.md
13, "review", "refactor", "existing"	阅读 refactoring-to-prompt-native.md
14, "anti-pattern", "mistake", "wrong"	阅读 anti-patterns.md
15, "success", "criteria", "verify", "checklist"	阅读 success-criteria.md
16, "hook", "hooks", "PreToolUse", "decision control", "async hook", "permissionDecision"	阅读 hooks-patterns.md
17, "cli", "command line", "stdout", "exit code", "--format", "--dry-run"	阅读 cli-agent-interface.md
18, "approval", "approve before send", "outbound", "ledger", "double-send"	阅读 operator-approval-loop.md
0, "quick start", "getting started", "overview", "introduction"	阅读 quick-start.md

阅读参考资料后，将其中的模式应用于用户的具体情境。

特定任务参考资料

在实现或审查相应行为之前，请阅读相关参考资料：

• 在实现 Agent 原生架构之前，请处理所有适用的架构检查清单条目：architecture-review-checklist.md。

现有的专项参考资料（适用于相应主题时）：

• durability-and-attestation.md。
• 对 hooks、skills 或提示词规则进行受控评估时，请阅读 intervention-evaluation.md。