Back to Details

agentic-readiness

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agentic Readiness

智能体就绪性审核

Default to audit-only. Present findings and wait for approval unless the user explicitly asks to implement changes.
默认仅执行审核操作。展示审核结果并等待用户批准，除非用户明确要求实施变更。

Audit workflow

审核工作流

  1. Read the repository's existing instruction chain before inspecting other files.
  2. Run from the repository root:
bash
python scripts/audit_repo.py --root .
Add 
--include-user-scope
only when the user explicitly wants personal Codex, Claude Code, and OpenCode configuration included. Never inspect credential stores or print secret values.
  1. Inspect the JSON report and verify findings against the actual build files, scripts, and repository layout. The script detects structural risks; it cannot prove that documented commands or architecture are current.
  2. Read the references needed for the task:
    • instruction-files.md for 
      AGENTS.md
      /
      CLAUDE.md
      ownership, discovery, routing, compatibility, and CodeAlive lessons learned.
    • rubric.md for scoring and priority definitions.
    • checklist.md for the full cross-agent audit.
    • best-practices.md for settings, workflows, context, and safety beyond instruction files.
  3. Report evidence before recommendations.
  1. 在检查其他文件之前，先阅读仓库现有的指令链。
  2. 从仓库根目录运行以下命令：
bash
python scripts/audit_repo.py --root .
仅当用户明确要求包含个人Codex、Claude Code和OpenCode配置时，才添加
--include-user-scope
参数。绝对不要检查凭证存储或打印机密值。
  1. 检查JSON报告，并对照实际的构建文件、脚本和仓库布局验证审核结果。该脚本可检测结构性风险，但无法证明文档化的命令或架构是最新的。
  2. 阅读完成任务所需的参考文档：
    • instruction-files.md：涵盖
      AGENTS.md
      /
      CLAUDE.md
      的归属、可发现性、路由、兼容性，以及CodeAlive的经验总结。
    • rubric.md：包含评分标准和优先级定义。
    • checklist.md：完整的跨智能体审核清单。
    • best-practices.md：指令文件之外的设置、工作流、上下文和安全最佳实践。
  3. 先报告证据，再给出建议。

Report shape

报告格式

Keep the report concise:
  • Executive summary: readiness, strongest area, main failure mode, first action.
  • Repository profile: scale, languages/frameworks, Git/worktree shape.
  • Instruction topology: canonical file, compatibility shim, nested routing, active-chain caveats, context-budget risks.
  • Agent surfaces: Codex/Codex App, Claude Code, and OpenCode settings, MCP, skills, and subagents actually present.
  • Issues: P0 through P3 with file paths and evidence.
  • Recommendations: concrete edits and verification commands.
Do not penalize a repository for omitting agent-specific configuration it does not need. Do flag a claimed cross-agent setup that one of the named agents cannot discover.
保持报告简洁：
  • 执行摘要：就绪状态、优势领域、主要问题、首要行动。
  • 仓库概况：规模、语言/框架、Git/工作树结构。
  • 指令拓扑：标准文件、兼容性垫片、嵌套路由、活动链注意事项、上下文预算风险。
  • 智能体界面：实际存在的Codex/Codex App、Claude Code和OpenCode设置、MCP、技能及子Agent。
  • 问题：从P0到P3的问题，包含文件路径和证据。
  • 建议：具体的编辑内容和验证命令。
若仓库未配置其不需要的智能体特定配置，无需扣分。但如果声称是跨智能体设置，而其中某个指定智能体无法发现相关配置，则需要标记。

Implementation workflow

实施工作流

When the user asks to apply changes:
  1. Confirm the requested scope from the conversation; do not ask again when it is already explicit.
  2. Preserve one source of truth. Prefer root 
    AGENTS.md
    plus a regular 
    CLAUDE.md
    containing 
    @AGENTS.md
    when the same rules should serve all three agents.
  3. Put scoped rules near their target paths. Add routing indexes only where they prevent real discovery mistakes.
  4. Keep generated directories, dependencies, caches, secondary worktrees, and unrelated subtrees out of routing tables.
  5. Turn non-negotiable rules into hooks, linters, or CI checks; instruction files are guidance, not enforcement.
  6. Show the diff, rerun the audit and tests, then explain any remaining intentional gaps.
当用户要求应用变更时：
  1. 确认对话中已明确的请求范围；若范围已明确，无需再次询问。
  2. 保留单一事实来源。当相同规则适用于三个智能体时，优先选择根目录下的
    AGENTS.md
    ，再搭配包含
    @AGENTS.md
    的常规
    CLAUDE.md
    。
  3. 将限定范围的规则放在其目标路径附近。仅在能避免实际发现错误的地方添加路由索引。
  4. 不要将生成的目录、依赖项、缓存、次要工作树和无关子树加入路由表。
  5. 将非协商规则转换为钩子、代码检查工具或CI检查；指令文件仅作为指导，而非强制要求。
  6. 展示差异，重新运行审核和测试，然后解释任何剩余的有意留白。

Large and multi-repository workspaces

大型及多仓库工作区

For more than 3,000 tracked files, emphasize navigation, bounded routing, focused verification, and retrieval support rather than copying documentation into startup context.
For a directory containing multiple child Git repositories, treat each child as an independent instruction root. Codex builds its instruction chain once per run/session, so changing a command's working directory does not load the child repository's files. Recommend an explicit meta-repository routing rule and verify each child from a fresh session or by reading its chain before the first operation.
对于跟踪文件超过3000个的仓库，重点关注导航、有限路由、聚焦验证和检索支持，而非将文档复制到启动上下文中。
对于包含多个子Git仓库的目录，将每个子仓库视为独立的指令根目录。Codex每次运行/会话仅构建一次指令链，因此更改命令的工作目录不会加载子仓库的文件。建议添加明确的元仓库路由规则，并在首次操作前从新会话读取子仓库的指令链，或直接读取其链来验证每个子仓库。