agent-readable-code

该技能面向让 AI 编码代理能正确阅读和修改的代码风格，核心启发式是“让只 grep 单个文件的人也能正确行动”。含六条以上实践：按领域语义命名（AR003，避免 Manager、Util、process 等泛化名），用纵向切片替代横向分层，控制文件规模与唯一性（AR001/AR002/AR008，文件超约 800 行、近似重复块、超长行均不利），依赖需静态显式（AR004/AR005，避免元编程、魔术字符串分发、超三层继承、barrel 重导出），边界处使用类型与准确注释（AR006，错误文档比缺失文档更糟），提供验证手段（AR007，测试与源码同目录、单条命令跑 lint+typecheck+test），并保持确定性与可注入副作用（随机种子、冻结时间、显式传入 clock/fetch/logger）。另含 Python、TypeScript 语言级建议，如 all、dataclass slots/frozen、branded types、判别联合、as const、从单一来源推断类型，以及训练数据卫生建议：优先主流稳定框架、锁定依赖版本。配套 scripts/lint.py 为零依赖 linter，支持 Python 与 TS/JS，命令示例：python scripts/lint.py <path>、--json、--rules AR001,AR003、--config my.yaml；可用 # agent-lint: disable=AR00X 内联抑制。不适用场景包括框架强制布局、公共 API 兼容优先、元编程即产品、固有重复、一次性脚本、集中式测试策略。资料未提供定价与安装步骤。