redis-py 仓库 AGENTS.md 同步审计工作流基于 sync-claude-md 命令的规范文档维护实践【免费下载链接】redis-pyRedis Python client项目地址: https://gitcode.com/GitHub_Trending/re/redis-py导读本文面向 redis-py 仓库的维护者与 AI Agent系统讲解如何基于仓库内的/sync-claude-md命令对仓库根目录的 AGENTS.mdAI 代理唯一权威指导文档执行一致性审计与同步更新。读完本文你将掌握完整的验证清单——包括 invoke 任务、pytest 选项、pytest marker、架构目录、关键符号引用等五大核对维度理解哪些内容必须补充、哪些内容禁止写入的边界规则以及编辑后的输出格式要求。这套工作流在完成新功能收尾或重大结构性变更后运行用于确保代理指导文档与代码库真实状态始终保持同步。一、工作流定位为什么需要同步 AGENTS.md在 redis-py 仓库中AGENTS.md 被定义为供参与本仓库的 AI 代理使用的唯一指导来源single source of guidance它同时承载项目参考资料命令、架构、依赖说明与贡献者流程规则两大职责。而根目录的 CLAUDE.md 全文仅有一行AGENTS.md是 AGENTS.md 的 include 引用不得被编辑——一旦直接编辑include 关系就会丢失并造成内容重复。因此当仓库经历功能收尾wrapping up a feature或重大结构性变更significant structural changes后就需要运行/sync-claude-md命令审计 AGENTS.md 是否与代码库当前状态一致并直接更新它。这条命令的完整执行指令存放在 .agents/commands/sync-claude-md/sync-claude-md.md而位于 .claude/commands/sync-claude-md.md 的入口文件只承担转发器角色它指明完整指令的位置并要求执行者完整阅读并严格遵循。值得说明的是命令入口与指令文档分置两处的设计.claude/存放轻量入口、.agents/存放完整规范也复用于其他命令例如 .claude/commands/add-new-command.md 同样是转发到 .agents/commands/add-new-command/add-new-command.md并附带命令规格模板 command-specification-template.md。二、执行前置三类输入准备在动手审计之前工作流要求先收集三份输入它们共同构成审计基线当前的 AGENTS.md动手前必须先完整读取它是待更新的基线文档所有增删改都以它为参照近期的 git 历史执行git log --oneline -40查看最近 40 条提交以及git log --diff-filterA --name-only --since3 months ago找出近三个月内新增的子系统文件——这是发现AGENTS.md 尚未记录的新增内容的最直接手段当前的文件/目录布局重点核对redis/、redis/asyncio/、redis/commands/、redis/_parsers/、tests/、.github/workflows/、.agents/、.claude/等目录的实际结构。三、验证清单逐节核对 AGENTS.md 的准确性3.1 Commands 部分三向交叉引用AGENTS.md 的 Commands 一节列举了所有invoke任务及其参数、pytest 选项和 pytest marker这一节需要做三组交叉引用1invoke 任务 ↔ tasks.py逐一核对 AGENTS.md 中提到的每个invoke任务是否在 tasks.py 中存在并检查是否存在错误的默认值、被重命名或删除的旗标、以及 conftest 选项的变更。以当前仓库实际状态为例invoke devenvtasks.py 的devenv任务默认执行docker compose --profile all up -d --build启动 standalone、replica、sentinel、cluster、redis-stack 等测试环境invoke tests按fixed_client→standalone→cluster的顺序依次运行三套测试对应 tasks.py L88-L105 的tests任务并透传--uvloop、--protocol2|3|、--legacy-responsestrue|false、--profile参数invoke standalone-tests/invoke cluster-tests分别运行单一套件其中 cluster 套件默认指向redis://localhost:16379/0TLS 场景使用rediss://localhost:27379/0见 tasks.py L153-L171invoke fixed-client-tests仅运行标记为fixed_client的测试tasks.py L109-L121invoke run-test-matrix执行protocol×legacy_responses全矩阵与 CI 行为一致tasks.py L197-L223invoke linters/invoke linters-fix运行ruff check、ruff format以及vulture redis whitelist.py --min-confidence 80tasks.py L34-L47vulture 的误报通过 whitelist.py 白名单抑制invoke all-tests串联 linters 与测试invoke build-docs生成 docs/ 下的 Sphinx HTML。2pytest 选项 ↔ tests/conftest.py 的pytest_addoptionAGENTS.md 声称测试插件在 tests/conftest.py 中通过pytest_addoptionL108-L184注册了--redis-url、--redis-ssl-url、--redis-mod-url、--protocol、--legacy-responses、--redis-cluster-nodes、--uvloop等选项审计时需逐一核实选项名与默认值。其中--protocol的默认值对应仓库当前的 RESP3 默认协议--legacy-responses接受true|false|default三态default表示不覆盖沿用客户端构造器默认值。3pytest marker 列表 ↔ pyproject.toml 的[tool.pytest.ini_options].markersAGENTS.md 列出的onlycluster/onlynoncluster、redismod、fixed_client、experimental、replica、ssl、pipeline、cp_integration、no_mock_connections等标记与 pyproject.toml L79-L92 中注册的 markers 应一一对应。这些标记的作用域语义是onlycluster/onlynoncluster——把单个测试限定到某种拓扑集群或单机redismod——需要 Redis 模块Stack 镜像在集群模式下跳过fixed_client——测试自带固定的客户端/配置被排除在 protocol/legacy 矩阵之外experimental、replica、ssl、pipeline、cp_integration、no_mock_connections——分别对应实验性功能、副本拓扑、TLS、管道、凭据提供方集成以及禁用自动 mock 连接夹具等场景。此外AGENTS.md 还注明 tests/test_scenario/ 与 tests/test_asyncio/test_scenario/ 属于需要外部基础设施Redis Enterprise、EntraID 等的场景测试会通过--ignore排除在默认的 standalone/cluster 套件之外——这一点同样可以在 tasks.py 的 standalone/cluster 测试命令参数中得到印证。3.2 Architecture 部分目录、符号与镜像核对这一节包含三项验证任务1子包清单与实际目录比对。逐项确认 AGENTS.md 中列出的模块与redis/commands/、redis/_parsers/、redis/multidb/、redis/asyncio/、redis/auth/、redis/observability/、redis/http/下的真实文件一致。例如redis/commands/下应有core.pyCoreCommands/AsyncCoreCommands混入类承载全部标准 Redis 命令、cluster.py同时导出READ_COMMANDS副本路由集合、sentinel.py、redismodules.py聚合 bf/、json/、search/、timeseries/、vectorset/ 各模块混入类、policies.pyPolicyResolver/StaticPolicyResolver路由视图、metadata.pyRequestPolicy/ResponsePolicy、CommandMetadata等命令元数据记录类型。2新增子系统检查。使用git log --diff-filterA --name-only并限定到redis/路径找出 AGENTS.md 上次更新之后新增的顶层包——例如redis/multidb/多数据库 Active-Active 客户端、redis/cache.py客户端缓存、redis/maint_notifications.py服务端推送的维护通知、redis/observability/OpenTelemetry 埋点都属于此类需要被 AGENTS.md 提及的新增子系统。3符号存活检查grep 验证。对 AGENTS.md 中引用的具体符号逐一 grep确认其仍然存在。当前仓库中可以验证的关键符号包括READ_COMMANDS、RequestPolicy、ResponsePolicy、CommandsParser位于 redis/_parsers/commands.py供集群客户端通过COMMAND INFO学习命令元数据、ExponentialWithJitterBackoffredis/backoff.py 中的默认退避策略。4同步/异步镜像断言抽查。AGENTS.md 声称同步栈redis/client.py、redis/cluster.py、redis/connection.py、redis/sentinel.py、redis/lock.py、redis/retry.py与异步栈redis/asyncio/下对应模块必须保持同步演进审计时应抽查redis/asyncio/下所列的异步等价模块是否真实存在。这套刻意重复的设计在 specs/sync_async_deduplication_analysis.md 中有专门记录也是后续流程中Sync / Async Consistency强制规则的前提。3.3 Python / 依赖说明与 pyproject.toml 对照AGENTS.md 的 Python 与依赖一节声明了requires-python 3.10、可选 extrashiredis、xxhash、ocsp、jwt、circuit_breaker、otel、Ruff 为唯一格式化/检查工具target-version py310、line-length 88等信息。审计时需要与 pyproject.toml 中的requires-python、[project.optional-dependencies]与[tool.ruff]配置逐项比对确认没有过期或错误。3.4 文档指针验证引用文件仍存在AGENTS.md 中指向其他文档的引用如 specs/sync_async_deduplication_analysis.md、specs/unified_responses_migration_guide.md、.agents/sync_async_type_hints_overload_guide.md、whitelist.py 等需要确认文件仍然存在、路径仍然有效避免代理被引导到 404 位置。四、写入规则什么内容才值得补充同步审计不是看到目录树变化就无脑追加。指令文档明确规定只有当某个新子系统、工作流或面向开发者的约定被引入且仅靠浏览目录树无法显而易见地推断出来时才需要添加简短说明。值得补充的典型内容有四类redis/下新的顶级包且承担独立的架构角色——例如redis/multidb/、redis/observability/、redis/auth/这类有自己的架构定位的子系统新的invoke任务或对既有任务有意义的变更新增旗标、默认值变化新的 pytest marker或关于测试组织方式的新约定新增的.agents/skills/或.agents/commands/技能以及specs/下记录了承重设计决策的新 spec 文件——未来代理应该知晓这些约定。五、红线清单什么内容严禁写入与之相对以下五类内容即使真实存在也不得写入 AGENTS.md逐文件的描述或任何ls就能发现的信息——AGENTS.md 是定位导航文档orienting document不是目录清单通用的 Python 或 git 建议——与仓库具体状态无关的泛泛之谈近期的 bugfix 或提交级变更——AGENTS.md 描述仓库的现状不描述历史任何从 README 或 CONTRIBUTING 中显而易见的内容——避免重复叙述同时编辑时应坚持小范围定向修改优先于整篇重写的原则保持 diff 最小化。六、输出规范编辑方式与变更摘要完成审计与必要编辑后工作流对输出有两项明确要求直接编辑 AGENTS.md使用编辑工具应用改动优先选择小范围、定向的编辑而非整体重写命令文档还特别强调编辑 AGENTS.md 时不要先请求确认——因为这是该命令的既定职责。编辑后打印一份 200 字以内的变更摘要按 Commands / Architecture / Other 三个分组说明改了什么、为什么改。最后一条同样重要如果检查后没有需要变更的内容必须明确说明无需变更而不是为了显得有产出而强行编辑文件。这与整个工作流事实优先、最小干预的精神一致——AGENTS.md 同步的本质是让指导文档始终如实反映代码库而不是制造无意义的工作量。七、工作流实操要点回顾综合来看/sync-claude-md命令的可执行闭环可以归纳为五步读基线完整读取 AGENTS.md明确它是唯一权威文档、CLAUDE.md 不可编辑查变更用git log --oneline -40与git log --diff-filterA --name-only --since3 months ago发现近期新增的子系统与文件逐节核对按 Commandsinvoke 任务 ↔ tasks.py、pytest 选项 ↔ tests/conftest.py、marker ↔ pyproject.toml、Architecture目录、符号 grep、sync/async 镜像、Python/依赖、文档指针四组清单完成交叉验证按规则增删只补充目录树无法直接看出的架构性新内容坚决不写文件级描述、通用建议与历史变更输出结果小范围定向编辑 AGENTS.md附 200 字以内按节分组的摘要无变更则明确声明。这套工作流的核心价值在于它把AI 代理指导文档与代码库失同步这一长期维护痛点固化为一条可执行、可验证、有边界的自动化命令确保任何时刻进入仓库的代理都能读到与当前代码状态精确一致的架构与流程说明。【免费下载链接】redis-pyRedis Python client项目地址: https://gitcode.com/GitHub_Trending/re/redis-py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 redis-py 仓库 AGENTS.md 同步审计工作流：基于 sync-claude-md 命令的规范文档维护实践
redis-py 仓库 AGENTS.md 同步审计工作流基于 sync-claude-md 命令的规范文档维护实践【免费下载链接】redis-pyRedis Python client项目地址: https://gitcode.com/GitHub_Trending/re/redis-py导读本文面向 redis-py 仓库的维护者与 AI Agent系统讲解如何基于仓库内的/sync-claude-md命令对仓库根目录的 AGENTS.mdAI 代理唯一权威指导文档执行一致性审计与同步更新。读完本文你将掌握完整的验证清单——包括 invoke 任务、pytest 选项、pytest marker、架构目录、关键符号引用等五大核对维度理解哪些内容必须补充、哪些内容禁止写入的边界规则以及编辑后的输出格式要求。这套工作流在完成新功能收尾或重大结构性变更后运行用于确保代理指导文档与代码库真实状态始终保持同步。一、工作流定位为什么需要同步 AGENTS.md在 redis-py 仓库中AGENTS.md 被定义为供参与本仓库的 AI 代理使用的唯一指导来源single source of guidance它同时承载项目参考资料命令、架构、依赖说明与贡献者流程规则两大职责。而根目录的 CLAUDE.md 全文仅有一行AGENTS.md是 AGENTS.md 的 include 引用不得被编辑——一旦直接编辑include 关系就会丢失并造成内容重复。因此当仓库经历功能收尾wrapping up a feature或重大结构性变更significant structural changes后就需要运行/sync-claude-md命令审计 AGENTS.md 是否与代码库当前状态一致并直接更新它。这条命令的完整执行指令存放在 .agents/commands/sync-claude-md/sync-claude-md.md而位于 .claude/commands/sync-claude-md.md 的入口文件只承担转发器角色它指明完整指令的位置并要求执行者完整阅读并严格遵循。值得说明的是命令入口与指令文档分置两处的设计.claude/存放轻量入口、.agents/存放完整规范也复用于其他命令例如 .claude/commands/add-new-command.md 同样是转发到 .agents/commands/add-new-command/add-new-command.md并附带命令规格模板 command-specification-template.md。二、执行前置三类输入准备在动手审计之前工作流要求先收集三份输入它们共同构成审计基线当前的 AGENTS.md动手前必须先完整读取它是待更新的基线文档所有增删改都以它为参照近期的 git 历史执行git log --oneline -40查看最近 40 条提交以及git log --diff-filterA --name-only --since3 months ago找出近三个月内新增的子系统文件——这是发现AGENTS.md 尚未记录的新增内容的最直接手段当前的文件/目录布局重点核对redis/、redis/asyncio/、redis/commands/、redis/_parsers/、tests/、.github/workflows/、.agents/、.claude/等目录的实际结构。三、验证清单逐节核对 AGENTS.md 的准确性3.1 Commands 部分三向交叉引用AGENTS.md 的 Commands 一节列举了所有invoke任务及其参数、pytest 选项和 pytest marker这一节需要做三组交叉引用1invoke 任务 ↔ tasks.py逐一核对 AGENTS.md 中提到的每个invoke任务是否在 tasks.py 中存在并检查是否存在错误的默认值、被重命名或删除的旗标、以及 conftest 选项的变更。以当前仓库实际状态为例invoke devenvtasks.py 的devenv任务默认执行docker compose --profile all up -d --build启动 standalone、replica、sentinel、cluster、redis-stack 等测试环境invoke tests按fixed_client→standalone→cluster的顺序依次运行三套测试对应 tasks.py L88-L105 的tests任务并透传--uvloop、--protocol2|3|、--legacy-responsestrue|false、--profile参数invoke standalone-tests/invoke cluster-tests分别运行单一套件其中 cluster 套件默认指向redis://localhost:16379/0TLS 场景使用rediss://localhost:27379/0见 tasks.py L153-L171invoke fixed-client-tests仅运行标记为fixed_client的测试tasks.py L109-L121invoke run-test-matrix执行protocol×legacy_responses全矩阵与 CI 行为一致tasks.py L197-L223invoke linters/invoke linters-fix运行ruff check、ruff format以及vulture redis whitelist.py --min-confidence 80tasks.py L34-L47vulture 的误报通过 whitelist.py 白名单抑制invoke all-tests串联 linters 与测试invoke build-docs生成 docs/ 下的 Sphinx HTML。2pytest 选项 ↔ tests/conftest.py 的pytest_addoptionAGENTS.md 声称测试插件在 tests/conftest.py 中通过pytest_addoptionL108-L184注册了--redis-url、--redis-ssl-url、--redis-mod-url、--protocol、--legacy-responses、--redis-cluster-nodes、--uvloop等选项审计时需逐一核实选项名与默认值。其中--protocol的默认值对应仓库当前的 RESP3 默认协议--legacy-responses接受true|false|default三态default表示不覆盖沿用客户端构造器默认值。3pytest marker 列表 ↔ pyproject.toml 的[tool.pytest.ini_options].markersAGENTS.md 列出的onlycluster/onlynoncluster、redismod、fixed_client、experimental、replica、ssl、pipeline、cp_integration、no_mock_connections等标记与 pyproject.toml L79-L92 中注册的 markers 应一一对应。这些标记的作用域语义是onlycluster/onlynoncluster——把单个测试限定到某种拓扑集群或单机redismod——需要 Redis 模块Stack 镜像在集群模式下跳过fixed_client——测试自带固定的客户端/配置被排除在 protocol/legacy 矩阵之外experimental、replica、ssl、pipeline、cp_integration、no_mock_connections——分别对应实验性功能、副本拓扑、TLS、管道、凭据提供方集成以及禁用自动 mock 连接夹具等场景。此外AGENTS.md 还注明 tests/test_scenario/ 与 tests/test_asyncio/test_scenario/ 属于需要外部基础设施Redis Enterprise、EntraID 等的场景测试会通过--ignore排除在默认的 standalone/cluster 套件之外——这一点同样可以在 tasks.py 的 standalone/cluster 测试命令参数中得到印证。3.2 Architecture 部分目录、符号与镜像核对这一节包含三项验证任务1子包清单与实际目录比对。逐项确认 AGENTS.md 中列出的模块与redis/commands/、redis/_parsers/、redis/multidb/、redis/asyncio/、redis/auth/、redis/observability/、redis/http/下的真实文件一致。例如redis/commands/下应有core.pyCoreCommands/AsyncCoreCommands混入类承载全部标准 Redis 命令、cluster.py同时导出READ_COMMANDS副本路由集合、sentinel.py、redismodules.py聚合 bf/、json/、search/、timeseries/、vectorset/ 各模块混入类、policies.pyPolicyResolver/StaticPolicyResolver路由视图、metadata.pyRequestPolicy/ResponsePolicy、CommandMetadata等命令元数据记录类型。2新增子系统检查。使用git log --diff-filterA --name-only并限定到redis/路径找出 AGENTS.md 上次更新之后新增的顶层包——例如redis/multidb/多数据库 Active-Active 客户端、redis/cache.py客户端缓存、redis/maint_notifications.py服务端推送的维护通知、redis/observability/OpenTelemetry 埋点都属于此类需要被 AGENTS.md 提及的新增子系统。3符号存活检查grep 验证。对 AGENTS.md 中引用的具体符号逐一 grep确认其仍然存在。当前仓库中可以验证的关键符号包括READ_COMMANDS、RequestPolicy、ResponsePolicy、CommandsParser位于 redis/_parsers/commands.py供集群客户端通过COMMAND INFO学习命令元数据、ExponentialWithJitterBackoffredis/backoff.py 中的默认退避策略。4同步/异步镜像断言抽查。AGENTS.md 声称同步栈redis/client.py、redis/cluster.py、redis/connection.py、redis/sentinel.py、redis/lock.py、redis/retry.py与异步栈redis/asyncio/下对应模块必须保持同步演进审计时应抽查redis/asyncio/下所列的异步等价模块是否真实存在。这套刻意重复的设计在 specs/sync_async_deduplication_analysis.md 中有专门记录也是后续流程中Sync / Async Consistency强制规则的前提。3.3 Python / 依赖说明与 pyproject.toml 对照AGENTS.md 的 Python 与依赖一节声明了requires-python 3.10、可选 extrashiredis、xxhash、ocsp、jwt、circuit_breaker、otel、Ruff 为唯一格式化/检查工具target-version py310、line-length 88等信息。审计时需要与 pyproject.toml 中的requires-python、[project.optional-dependencies]与[tool.ruff]配置逐项比对确认没有过期或错误。3.4 文档指针验证引用文件仍存在AGENTS.md 中指向其他文档的引用如 specs/sync_async_deduplication_analysis.md、specs/unified_responses_migration_guide.md、.agents/sync_async_type_hints_overload_guide.md、whitelist.py 等需要确认文件仍然存在、路径仍然有效避免代理被引导到 404 位置。四、写入规则什么内容才值得补充同步审计不是看到目录树变化就无脑追加。指令文档明确规定只有当某个新子系统、工作流或面向开发者的约定被引入且仅靠浏览目录树无法显而易见地推断出来时才需要添加简短说明。值得补充的典型内容有四类redis/下新的顶级包且承担独立的架构角色——例如redis/multidb/、redis/observability/、redis/auth/这类有自己的架构定位的子系统新的invoke任务或对既有任务有意义的变更新增旗标、默认值变化新的 pytest marker或关于测试组织方式的新约定新增的.agents/skills/或.agents/commands/技能以及specs/下记录了承重设计决策的新 spec 文件——未来代理应该知晓这些约定。五、红线清单什么内容严禁写入与之相对以下五类内容即使真实存在也不得写入 AGENTS.md逐文件的描述或任何ls就能发现的信息——AGENTS.md 是定位导航文档orienting document不是目录清单通用的 Python 或 git 建议——与仓库具体状态无关的泛泛之谈近期的 bugfix 或提交级变更——AGENTS.md 描述仓库的现状不描述历史任何从 README 或 CONTRIBUTING 中显而易见的内容——避免重复叙述同时编辑时应坚持小范围定向修改优先于整篇重写的原则保持 diff 最小化。六、输出规范编辑方式与变更摘要完成审计与必要编辑后工作流对输出有两项明确要求直接编辑 AGENTS.md使用编辑工具应用改动优先选择小范围、定向的编辑而非整体重写命令文档还特别强调编辑 AGENTS.md 时不要先请求确认——因为这是该命令的既定职责。编辑后打印一份 200 字以内的变更摘要按 Commands / Architecture / Other 三个分组说明改了什么、为什么改。最后一条同样重要如果检查后没有需要变更的内容必须明确说明无需变更而不是为了显得有产出而强行编辑文件。这与整个工作流事实优先、最小干预的精神一致——AGENTS.md 同步的本质是让指导文档始终如实反映代码库而不是制造无意义的工作量。七、工作流实操要点回顾综合来看/sync-claude-md命令的可执行闭环可以归纳为五步读基线完整读取 AGENTS.md明确它是唯一权威文档、CLAUDE.md 不可编辑查变更用git log --oneline -40与git log --diff-filterA --name-only --since3 months ago发现近期新增的子系统与文件逐节核对按 Commandsinvoke 任务 ↔ tasks.py、pytest 选项 ↔ tests/conftest.py、marker ↔ pyproject.toml、Architecture目录、符号 grep、sync/async 镜像、Python/依赖、文档指针四组清单完成交叉验证按规则增删只补充目录树无法直接看出的架构性新内容坚决不写文件级描述、通用建议与历史变更输出结果小范围定向编辑 AGENTS.md附 200 字以内按节分组的摘要无变更则明确声明。这套工作流的核心价值在于它把AI 代理指导文档与代码库失同步这一长期维护痛点固化为一条可执行、可验证、有边界的自动化命令确保任何时刻进入仓库的代理都能读到与当前代码状态精确一致的架构与流程说明。【免费下载链接】redis-pyRedis Python client项目地址: https://gitcode.com/GitHub_Trending/re/redis-py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考