分享自用PowerShell环境Codex系统提示词片段

背景

在 Windows 环境下使用 AI 代码辅助工具（如 Codex）时，许多开发者习惯借助 WSL2 来获得类 Linux 的流畅体验。然而 WSL2 占用内存较高，且文件系统与 Windows 原生环境存在隔阂——通过目录直接打开文件夹或编辑器时不够方便。因此，原作者尝试将工作流迁移到原生的 Windows PowerShell，并经过一段时间的调试，找到了一个能够减少报错、提升执行速度的系统提示词片段。该片段通过约束 PowerShell 的使用行为和搜索策略，显著改善了 Codex 在 Windows 下的表现。

核心内容

原文分享了一个自用的系统提示词，放在 ~/.codex/AGENTS.md 文件中。该提示词主要包含两大部分：PowerShell 使用指南 和 搜索指南，旨在避免常见的 PowerShell 报错，并提高命令执行效率。

PowerShell 使用指南

1. 默认使用 non-login shell：避免加载用户 profile 带来的别名、提示符集成、环境变量污染。只有当指令明确依赖用户 shell 配置时，才使用 login/profile shell。
2. 优先使用 PowerShell 原生命令：在 Windows 上与文件系统或环境交互时，优先使用 PowerShell cmdlet，而非 Bash 命令。
3. 显式启动 PowerShell 时默认加 -NoProfile：使用 powershell -NoProfile 或 pwsh -NoProfile，避免用户 profile 脚本、提示符集成、别名和自定义 shell 的影响。只有在指令有意依赖用户 PowerShell profile 时才省略 -NoProfile。
4. 不混用 Bash 和 PowerShell 语法：同一命令或脚本中不能混用两种 shell 的语法。
5. 多行脚本设置 $ErrorActionPreference = 'Stop'：在脚本开头附近添加该行，防止错误发生后继续静默执行。
6. 写文本文件时指定 -Encoding UTF8：在 cmdlet 支持的情况下，使用 UTF8 编码。
7. 结构化数据处理优先用对象管道：使用 Select-Object、Where-Object、ForEach-Object 等 PowerShell 对象管道，而不是脆弱的字符串切割。

搜索指南

1. 高效且低噪声的搜索：大范围文件或文本搜索优先使用 rg / rg --files，而不是递归的 Get-ChildItem。从尽可能窄的已知目录开始搜索。
2. 排除高噪声目录：在搜索大目录（如用户主目录）时，排除 .git、node_modules、虚拟环境文件夹、包缓存等。只在需要时才使用 --hidden 参数。
3. 复杂正则使用 rg --pcre2：对于需要正则 look-around（如 (?!...)、(?=...)、(?<!...)、(?<=...)）的情况，使用 --pcre2 模式。
4. PowerShell 中引用复杂模式：在 PowerShell 中使用单引号包裹 rg 的复杂模式，并转义单引号为 ''。
5. 固定字符串搜索用 rg -F：对于固定字符串，使用 -F 参数；复杂命令先测试再分享。

关键要点

• 减少 Profile 干扰：默认使用 -NoProfile 或 non-login shell，避免用户自定义别名、提示符和环境污染导致的意外错误。
• 纯 PowerShell 化：文件、环境操作全部使用原生 cmdlet，不混用 Bash 语法，确保脚本在 Windows 下行为一致。
• 错误处理前置：多行脚本中设置 $ErrorActionPreference = 'Stop'，防止失败后继续执行，避免隐藏问题。
• 编码明确：写文本文件时指定 -Encoding UTF8，避免因默认编码不一致导致的乱码或解析错误。
• 对象管道优于字符串切割：利用 PowerShell 的对象管道处理结构化数据，提高可靠性和可维护性。
• 搜索工具选择：优先使用 rg（ripgrep）代替 Get-ChildItem，从窄目录开始，并主动排除噪声目录，提升搜索速度并降低噪音。
• 正则与固定字符串区分：复杂正则用 rg --pcre2，固定字符串用 rg -F，在 PowerShell 中正确引用模式。
• 配置文件位置：提示词片段应放在 ~/.codex/AGENTS.md 下，供 Codex 等 AI 工具读取。

意义与影响

该提示词片段为 Windows 原生 PowerShell 环境下使用 AI 代码辅助工具（如 Codex）提供了一套系统性的最佳实践。它针对 PowerShell 与 Bash 混用、profile 加载、错误处理、编码问题、搜索效率等常见痛点给出了具体约束，使 AI 生成的命令更可靠、执行更快、报错更少。对于希望从 WSL2 迁移到原生 Windows 命令行环境的开发者，这组提示词能显著降低迁移成本，提升开发体验。同时，该思路也适用于其他 AI 代码助手（如 GitHub Copilot、GPT 等）的 prompt 设计，启示开发者通过显式声明环境约束来引导 AI 输出更符合预期的指令。