在Codex中设置全局Agent规则的最佳实践参考

背景

在 AI 辅助编程工具（如 OpenAI 的 Codex）日益普及的当下，如何让这些 Agent 在特定操作系统环境下可靠、合规地执行命令，成为开发者关注的问题。一位 LINUX DO 论坛的用户在使用 Codex 时，发现其生成的 shell 命令默认倾向类 Unix 语法（Bash/zsh），但在 Windows 环境下（主要终端为 PowerShell 7+），这种默认行为会导致命令执行失败或产生意外后果。该用户让 Codex 自行草拟了一段「命令行执行原则」，作为全局 Agents 的规范文件（agents.md），并在此基础上询问社区：是否存在现成的、轻量级的「焚决」（即最佳实践 / 规则集）可供参考，以便在不引入复杂工作流框架（如 oh-my-xxx）的前提下，让 Codex 产出更稳健、更符合 Windows 习惯的代码。用户自身也总结了几条零散的习惯，例如「尽量不要自己造轮子」「必须先阅读文档再写代码」「必须使用 uv 管理虚拟环境和运行」等，但希望找到更完整、更规范的现成参考答案。

核心内容

用户展示的 Codex 草拟原则是一份针对 Windows PowerShell 7+ 环境的命令行执行规范，全文如下（原文直述）：

命令行执行原则

本环境为 Windows，主要终端是 PowerShell 7+（pwsh）。执行任何终端命令时，必须使用 PowerShell 语法，不得使用 Bash、sh、zsh、cmd.exe 或类 Unix shell 的专用语法，除非用户明确要求。

编写命令时应遵守以下规则：

• 使用 PowerShell 原生命令、语法和管道，例如 Get-ChildItem、Select-String、Where-Object、ForEach-Object、Join-Path、Test-Path。
• 路径使用 Windows/PowerShell 兼容写法，优先使用 -LiteralPath 处理可能包含空格或特殊字符的路径。
• 不使用 Bash 风格语法，例如 VAR=value command、export VAR=value、grep、sed、awk、cat <<EOF、2>/dev/null、rm -rf、&& 链接复杂命令等。
• 不提交或执行空命令。命令字符串必须包含实际可执行内容，不能是空字符串、仅空白、仅注释，或由条件拼接导致的空片段。
• 如果需要组合多步操作，优先写成清晰的 PowerShell 语句；复杂逻辑应使用可读的多行 PowerShell，而不是强行压缩成一行。
• 删除、移动、覆盖文件前，应确认目标路径明确，递归删除尤其要先校验解析后的绝对路径位于预期工作区内。
• 若某个工具本身跨平台，例如 git、node、python、uv、pnpm，可以直接调用该工具，但外围的变量、路径、重定向、循环、条件判断仍必须使用 PowerShell 语法。
• 除非用户明确要求，否则所有 shell_command 都必须假定运行在 PowerShell 7+ 中，并严格使用 pwsh 语法。任何 Bash/cmd 风格命令都视为不合规。

在此基础上，用户提出了自己的困惑与期望：目前仍打算主力使用 Codex，不希望引入复杂的「oh-my-xxx」工作流，但需要一些轻量级的「焚决」参考。用户自己想到的零散习惯包括：

• 尽量不要自己造轮子（ask 确认）
• 必须先阅读文档再写代码
• 必须使用 uv 管理虚拟环境和运行
• 代码应保持同文件/项目的风格一致
• ……等等

用户期待社区能提供现成的作业（完整的最佳实践文档）供直接抄用。

关键要点

• 操作系统与环境标识：明确声明当前环境为 Windows，主要终端为 PowerShell 7+（pwsh），任何生成的 shell 命令必须严格遵循 PowerShell 语法，禁止混入 Bash、cmd 等其他 shell 语法。
• 强制使用 PowerShell 原生命令：诸如 Get-ChildItem、Select-String、Where-Object 等 cmdlet 取代 grep、sed、awk、ls 等类 Unix 工具。
• 路径处理规范：路径必须采用 Windows/PowerShell 兼容写法，优先使用 -LiteralPath 参数以应对空格和特殊字符；对递归删除等危险操作要求先校验绝对路径是否在预期工作区内。
• 禁止 Bash 特有语法：禁止 export、VAR=value command、重定向 2>/dev/null、rm -rf、&& 链式命令等写法。
• 空命令禁止：禁止提交或执行空字符串、仅包含空白或注释的命令，要求命令字符串始终包含实际可执行内容。
• 复杂操作要求多行可读：鼓励将多步操作拆分为清晰的 PowerShell 多行语句，而非强行压缩为一行。
• 跨平台工具处理：对于 git、node、python、uv、pnpm 等跨平台工具可以直接调用，但外围的变量、路径、重定向、循环、条件判断仍必须使用 PowerShell 语法。
• 默认合规假设：除非用户明确要求，所有 shell_command 默认运行在 PowerShell 7+ 中，违反者视为不合规。
• 用户个人最佳实践诉求：用户期望采用轻量级规则集，避免自己造轮子，先读文档再写代码，使用 uv 管理虚拟环境和运行，保持项目内代码风格一致，并希望获得社区现成的「焚决」文档。

意义与影响

这份命令行执行原则的提出，标志着 AI 编程 Agent 从通用性向环境适配性的一次深化实践。对于 Windows 生态下的开发者而言，Codex 等 LLM 默认输出类 Unix 命令的趋势长期存在，若缺乏明确的约束规则，Agent 生成的操作可能直接损坏文件系统（例如误用 rm -rf）、混淆路径解析或导致管道错误。该原则通过强制指定 PowerShell 语法，系统性解决了这些隐患，使 AI Agent 在 Windows 上达到与类 Unix 环境同等的可靠度。

另一方面，用户对「轻量级焚决」的诉求反映了社区的真实痛点：现有的复杂工作流（如 oh-my-zsh 式的模型提示框架）学习成本高、配置重，而轻量化、可复用的最佳实践文档更贴合日常开发场景。用户列举的个人习惯（先读文档、用 uv 管理环境、保持风格一致）其实已经触及了 AI 协作的核心原则——让 Agent 充分理解上下文，避免胡猜。若能将这些原则结合本贴中的 PowerShell 规则，整理成一份标准化的 agents.md 模板，将极大降低 Windows 开发者使用 Codex 的门槛，甚至可能成为类似项目的行业惯例。

同时，这条帖子也启示了 AI 对话与社区知识沉淀的新模式：由用户主动向 Agent 索取规范，再由社区讨论打磨，最终形成可复用的最佳实践。这种「人→AI→社区→标准化」的闭环，有望在未来 AI 技能分享中变得更加普遍。