implicit-token-savings

implicit-token-savings

针对实际问题，选择足以解决问题的最精简本地 shell 命令。

如果精简输出足以回答问题，就优先使用，尤其是在用户明确要求时。任务需要时，直接查看已知文件、相关差异或完整输出；初步摘要并非必需。

决策树

你现在需要什么？

• 仓库结构、顶层文件或候选路径

  • 从 ls -1、tree -L 2 或 rg --files 开始
  • 阅读 references/filesystem.md

• 特定符号、字面内容、堆栈跟踪或 TODO

  • 从 rg -n 开始
  • 阅读 references/filesystem.md

• 文件片段或行范围

  • 如果有，优先使用运行环境提供的定向读取工具
  • 否则使用 sed -n 'start,endp' file、head -n 80 或 tail -n 80
  • 阅读 references/filesystem.md

• 工作树状态、变更范围或近期历史记录

  • 从 git status --short、git diff --stat、git diff --name-only 或 git log --oneline 开始
  • 阅读 references/git.md

• 暂存、提交或推送

  • 仅暂存预期路径
  • 在获准提交前，检查所有已暂存的变更；使用摘要了解范围，使用代码块了解语义
  • 只有在获准推送且已知预期远程仓库和目标位置时，才使用 HEAD
  • 阅读 references/git.md

• 特定技术栈的测试、代码检查或容器健康状况

  • 从现有的、最精简的技术栈原生命令开始：cargo test、npm test、ruff check、pytest、go test 或 docker ps
  • 阅读 references/runners.md

• 首选命令不可用

  • 遵循回退矩阵
  • 阅读 references/patterns.md

默认操作规则

1. 根据已知上下文直接选择足够的命令。路径未知时，清点文件有帮助；目标文件已知时则不需要。
2. 明确限定范围。询问范围时使用 --files、--name-only 或 --stat；询问语义时输出内容。
3. 使用 rg 查找未知文件或匹配行；读取已知的相关文件时，无需先进行搜索。
4. 检查行为时，直接使用指定路径的 git diff。摘要有助于了解规模或文件列表，但无法说明语义。
5. 使用有针对性的测试获取本地反馈，并在交付前运行仓库要求的所有验证。针对性测试不能替代必需的完整测试套件。
6. 如果其他工具或脚本会使用输出，优先选择机器可读格式：--json、--format '{{json .}}'、jq -r。
7. 根据已知需求选择简洁、结构化或完整输出。保留错误、退出状态和失败详情；绝不压缩掉安全决策所需的证据。
8. 如果首选工具不可用，使用最接近且成本更低的替代方案，不要停滞不前。

快速参考

根据当前问题选择一行；备选项不是必需的操作顺序。

需求	简洁选项	有用时的备选项	原因
仓库顶层清单	ls -1	ls -lah 或 tree -L 2	只需了解概况时，文件名比装饰性输出更实用
目录结构	tree -L 2 path/	tree -a -L 3 path/	限制深度可保持结构清晰易读
仅查找候选路径	rg --files path/	rg --files path/ | rg 'pattern'	完全避免打开文件内容
搜索文本或符号	rg -n -F 'needle' path/	rg -n 'regex' path/	根据需要选择字面匹配或模式匹配
文件摘录	sed -n '1,80p' file	需要整个文件的上下文时完整读取	一次读取足够且有用的上下文
工作树状态	git status --short --branch	git status	对大多数决策而言，简短形式已足够
变更范围或语义	git diff --stat	查看路径用 git diff --name-only；查看语义用 git diff -- path	根据问题所需选择详细程度
最近历史	git log --oneline --decorate -n 15	git log --stat -- path	提交标题能快速回答许多问题
暂存并审查	git add -- path && git diff --cached --stat	git diff --cached -- path	只审查即将提交的内容
已获授权时推送当前分支	git push -u origin HEAD	目标不明时先检查目标	HEAD 是简写，不代表已获推送授权
Node 测试范围	npm test -- <runner-args>	不清楚标志时使用 npm test -- --help	使用项目已知的运行器约定
Rust 测试范围	cargo test name -- --nocapture	cargo test package::module::name	选择测试筛选器，获取有针对性的反馈
Python lint 范围	ruff check path/	ruff check path/ --fix	明确执行修复
Python 测试范围	pytest -q tests/test_file.py -k expr	pytest -q tests/	根据需要选择有针对性的反馈或套件覆盖
Go 测试范围	go test ./pkg/... -run Pattern	go test ./...	包和 -run 筛选器可减少干扰信息
容器清单	docker ps --format '{{json .}}'	docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'	结构化行更便于筛选或汇总

阅读指南

任务	阅读
仓库结构、搜索和针对性文件读取	references/filesystem.md
简洁的 git 状态、差异、历史、暂存和推送模式	references/git.md
精简的测试、lint 和容器命令	references/runners.md
根据上下文选择命令和备用方案	references/patterns.md
结果缺失、过度精简造成的错误和命令陷阱	references/gotchas.md

注意事项

1. rg 会遵循忽略规则。结果缺失时，通常需要使用 --hidden、-u 或 --debug，而不是切换工具。
2. tree 用于查看结构，不代表事实。尽早限制深度，否则会把 token 浪费在目录展示上。
3. 只需读取一部分内容时，sed -n 比 cat 更省；但确定所需的短文件后，反复分段读取的成本可能高于一次完整读取。
4. git diff --stat 会隐藏语义。对行为下结论前，应进一步查看指定路径的差异。
5. npm test 只会在 -- 之后转发额外的运行器标志。
6. docker ps 即使成功，你关心的容器也可能处于不健康状态。应查看 Status，而不只是确认容器存在。
7. 如果只涉及一个文件，git add . 就违背了节省 token 的原则。应暂存明确指定的路径。

辅助脚本

• scripts/probe_implicit_token_savings.py 会检测可用工具，并在临时本地测试文件上验证精简命令的行为。
• scripts/validate.py 会检查打包、必需文件和语法。
• scripts/test_skill.py 会运行验证、eval 覆盖率检查、交叉引用检查和探测测试套件。
• templates/session-checklist.md 是一份可复用的清单，可用于启动低干扰编码会话。

当指导不再有帮助时

如果简洁的命令失败或隐藏了所需证据，请使用更完整的输出，并查阅已安装的帮助文档或与版本匹配的官方文档。保留失败和未知情况，不要为了优化而将其消除。如果示例已过时，或带来的工作量大于它所节省的工作量，请提出规范的技能更新，并注明工具/版本和复现步骤。不要悄悄编辑已安装的副本，也不要发布该提案。