Caffeine 仓库的 AI Agent 协作入口：从 AGENTS.md 引导到 .claude 工程规范体系

后端缓存抽象【免费下载链接】caffeineA high performance caching library for Java项目地址https://gitcode.com/gh_mirrors/ca/caffeine点击查看免费下载AGENTS.md 是 Caffeine 缓存库为 AI AgentClaude Code 等设计的工具无关引导层它本身不承载规则而是将权威规范指向.claude/CLAUDE.md并约定规则、文档、技能、钩子的加载方式。本文以该入口文档为骨架结合仓库真实的构建脚本、源码与测试组织完整拆解这套面向 Agent 的工程协作体系如何加载规则、如何按需查阅参考文档、如何跑通构建/测试/静态分析/基准命令以及.claude/下规则rules、文档docs、技能skills、钩子hooks与审计代理agents各自的分工帮助读者快速上手用 Agent 分析、审计和修改这一高性能 Java 缓存项目。AGENTS.md 的角色一个薄而明确的引导层AGENTS.md全文只有三个要点却定义了整个仓库与 AI Agent 协作的基本原则权威规范单点化仓库的规范正文存放在.claude/CLAUDE.md任何 Agent 在分析或修改仓库之前都必须完整阅读该文件。规则按需加载对于无法原生加载 Claude Code 扩展的工具需要模拟其行为——在任务范围或涉及路径确定后检查.claude/rules/*.md及其pathsfrontmatter读取所有匹配的规则没有paths的规则在主题相关时全仓库生效无法确定适用性时就阅读它。文档按需参考.claude/docs/*.md是需求驱动的参考文档在报告缺陷或修改行为之前应依据.claude/CLAUDE.md中的路由指引读取相关文档。规范单一来源共享规范和可复用内容只维护在.claude/下不要复制或镜像到工具专属目录避免多份拷贝漂移。这种入口文件极薄、规范文件集中、加载机制显式的设计保证任何 Agent 工具无论是否原生支持 Claude Code 扩展都能以统一方式进入项目上下文。从仓库结构看.claude/下实际包含agents/、docs/、hooks/、rules/、skills/、CLAUDE.md、settings.json七类内容AGENTS.md正是它们的总入口。规范主体.claude/CLAUDE.md 的完整内容地图.claude/CLAUDE.md是仓库权威工程规范覆盖构建、测试、静态分析、基准、风格、架构、代码生成与项目结构等主题。下面按章节逐层展开。构建与测试一条命令跑全套仓库使用 Gradle 构建核心模块是caffeine。规范给出的基本命令./gradlew :caffeine:build # Full build ./gradlew :caffeine:test --tests ClassName # Single test class ./gradlew :caffeine:test --tests ClassName.methodName # Single method ./gradlew :caffeine:compileTestJava # Compile tests only规范特别强调单个测试方法即使横扫完整的CacheSpec矩阵也可以放心执行但应避免在本地跑整个类或全量测试套件CI 会按 40 个 worker 分片跑完整矩阵。这是对caffeine/src/test/java下大量参数化测试的现实约束。测试过滤用 -P 标志缩小矩阵测试类通过CacheSpec参数化CacheProvider提供不同缓存配置组合。可用-P标志按维度过滤./gradlew :caffeine:test -Pimplementationcaffeine # Cache type (caffeine/guava) ./gradlew :caffeine:test -Pkeysstrong # Key reference (strong/weak) ./gradlew :caffeine:test -Pvaluesstrong # Value reference (strong/weak/soft) ./gradlew :caffeine:test -Pcomputesync # Compute mode (sync/async) ./gradlew :caffeine:test -Pstatsenabled # Stats recording (enabled/disabled)这五个维度缓存实现、键引用类型、值引用类型、计算模式、统计开关几乎穷尽了 Caffeine 的可配置组合面是理解缓存行为边界的捷径。implementationguava对应guava/适配器模块valuessoft对应软引用值computeasync对应异步计算。专项测试套件十一种并发与兼容性测试这是 Caffeine 工程体系中最有特色的部分——一个缓存库同时维护十余个专项测试源集从不同角度验证正确性./gradlew :caffeine:frayTest # Fray concurrency interleaving ./gradlew :caffeine:lincheckTest # LinCheck linearizability ./gradlew :caffeine:fuzzTest # Fuzzing (Jazzer) ./gradlew :caffeine:jcstress # JCStress concurrency stress tests ./gradlew :caffeine:googleTest # Guava collections tests ./gradlew :caffeine:apacheTest # Apache Commons collections tests ./gradlew :caffeine:eclipseTest # Eclipse Collections collections tests ./gradlew :caffeine:jctoolsTest # JCTools collections tests ./gradlew :caffeine:jsr166Test # JSR-166 collections tests ./gradlew :caffeine:openjdkTest # OpenJDK collections tests ./gradlew :caffeine:moduleTest # Java module system tests ./gradlew :caffeine:osgiTest # OSGi bundle tests这些测试源集在仓库中有完整对应目录caffeine/src/frayTest/、caffeine/src/lincheckTest/、caffeine/src/fuzzTest/、caffeine/src/jcstress/、caffeine/src/googleTest/、caffeine/src/apacheTest/、caffeine/src/eclipseTest/、caffeine/src/jctoolsTest/、caffeine/src/jsr166Test/、caffeine/src/openjdkTest/、caffeine/src/moduleTest/以及guava/src/osgiTest/、jcache/src/osgiTest/。其思路是用外部权威测试集合OpenJDK 的Map测试、Guava 的LocalCache测试、Eclipse Collections 的MutableMap测试、Apache Commons、JSR-166 并发测试等来交叉验证自定义实现属于高强度的契约符合性测试策略。规范还规定测试不允许被Disabled或跳过——JUnit 报告为 skipped 的测试会导致构建失败Gradle 用onlyIf跳过的任务不算。静态分析ErrorProne NullAway 常驻SpotBugs/PMD 可选./gradlew :caffeine:build -Pspotbugs # SpotBugs ./gradlew :caffeine:build -Ppmd # PMD .github/scripts/analyze.sh # allErrorProne 与 NullAway 在每次构建中都会运行。依据.claude/rules/errorprone.md的说明NullAway 违规是错误而非警告注解库使用 JSpecifyorg.jspecifymodule-info.java中模块级NullMarked使所有类型默认非空仅在有意的 null 场景使用Nullable。全项目只有约 9 个 main 源文件存在抑制注解原则是优先修复而非抑制。基准、内存布局与压力测试./gradlew jmh -PincludePatternGetPutBenchmark # JMH microbenchmarks ./gradlew :caffeine:memoryOverhead # JOL object layout analysis ./gradlew :caffeine:stress --workload read --duration PT30S # Stress testing (read, write, refresh)jmh任务通过caffeine/src/jmh/java下的 JMH 基准类运行微基准如DelegationBenchmark、FactoryBenchmark、SlotLookupBenchmarkmemoryOverhead使用 JOL 分析节点对象的内存布局与gradle/plugins/src/main/kotlin/analyze/object-layout.caffeine.gradle.kts插件对应stress以 read/write/refresh 三种负载做压力测试时长由--duration控制ISO-8601 格式如PT30S。风格与贡献约定代码风格Google Java Style贡献者必须签署 CLA指南中特别提醒 Agent不要盲目推荐未经验证的依赖版本、Semgrep 规则集或工具集成项目中的有损/尽力而为语义读缓冲区丢事件、近似频率计数、最终一致性是有意设计取舍而非缺陷报告前应阅读.claude/docs/design-decisions.md。架构地图核心模块一览.claude/CLAUDE.md给出核心代码位置caffeine/src/main/java/com/github/benmanes/caffeine/cache/并逐文件标注职责文件职责BoundedLocalCache.java主缓存逻辑驱逐、过期、计算FrequencySketch.javaTinyLFU 准入频率计数器WindowClimber.java自适应窗口大小调节的爬坡器BoundedBuffer.java记录读事件的分条环形缓冲区MpscGrowableArrayQueue.java写缓冲区多生产者单消费者TimerWheel.java分级时间轮支持可变过期时间Node.java节点接口实现类由代码生成测试位于caffeine/src/test/java/com/github/benmanes/caffeine/cache/测试工具Truth 断言、测试线程工具、期望异常等在caffeine/src/testFixtures/java/com/github/benmanes/caffeine/testing/。这些文件都能在仓库中逐一找到是阅读 Caffeine 内部机制的精确入口例如TimerWheel.java实现分层时间轮BoundedBuffer.java实现读记录缓冲FrequencySketch.java实现 TinyLFU 的计数草图WindowClimber.java则根据命中率变化调整准入窗口大小。代码生成Node 类由 javaPoet 生成切勿手改Node的具体实现类如PS、PW、PSAWMW等由 javaPoet 生成规范明确永远不要编辑caffeine/build/generated/下的文件应修改caffeine/src/javaPoet/java/下的生成器。./gradlew :caffeine:generateNodes :caffeine:generateLocalCaches节点命名有严格编码规则理解后可见名知义键/值引用类型P强键F弱键S强值W弱值D软值后缀A访问时间W写时间R刷新MS无权重驱逐MW有权重驱逐。例如PSAWMW表示强键强值、记录访问时间与写时间、带权重的节点。这套命名直接反映缓存配置的特征组合与Caffeine构建器的weakKeys()、softValues()、expireAfterAccess()、maximumWeight()等选项一一对应。规则系统paths frontmatter 驱动的按需加载.claude/rules/*.md是项目约定的规则文件每个文件头部有pathsfrontmatter 声明适用路径。以已存在的规则为例.claude/rules/concurrency.mdpaths覆盖caffeine/src/main/java/**与各测试源集规定锁顺序evictionLock→ CHM bin 锁 →synchronized(node)、节点状态编码alive/retired/dead、写缓冲区任务不丢失等并发约定.claude/rules/testing.md规定单测用 JUnit Jupiter Truth Awaitility、新测试应遵循CacheSpec参数化模式、GC 相关测试用GcFinalization与Awaits.awaitFullGc()并附带一份测试发现指南按公共 API 面Cache→CacheTest、AsyncCache→AsyncCacheTest等与功能面驱逐→EvictionTest、过期→ExpirationTest/ExpireAfter*Test等给出应优先运行的测试类.claude/rules/errorprone.mdErrorProne/NullAway 配置、抑制写法与禁用检查清单.claude/rules/design-decisions.md驱逐与维护相关的评审不变量权重 0 固定条目、每周期最多驱逐EXPIRATION_THRESHOLD1000 个、草图只增不减等.claude/rules/async-cache.md异步缓存委托模式CompletableFutureV包装、未来生命周期与弱/软值不支持等约定.claude/rules/simulator.mdsimulator 模块的 HOCON 配置、record(AccessEvent)/finished()/stats()策略接口、./gradlew simulator:run等运行方式.claude/rules/github-actions.mdCI 工作流中动作引用与 actionlint 忽略规则。加载语义由 AGENTS.md 定义规则文件与其paths匹配的改动范围绑定命中即读无paths的规则在主题相关时全仓库生效不确定就读。这实现了上下文最小化——Agent 不必加载全部规则只加载与当前任务相关的部分。按需参考文档docs 目录的路由指南.claude/docs/*.md存放深度参考CLAUDE.md中专门有一节何时读哪份文档的路由指引并发或线程安全相关工作 →.claude/docs/synchronization.md锁层次、访问模式、回调调用点评审代码 → 先读.claude/docs/design-decisions.md防止误报审计则在记录自身发现后的 Phase 1.5 阅读撰写或修改测试 →.claude/docs/testing.mdCacheSpec 参数化、Truth 主题、测试工具理解算法选择 →.claude/docs/research-foundations.md论文到实现的映射TinyLFU、BP-Wrapper 等涉及窗口爬坡器determineAdjustment→.claude/docs/hill-climber.md自适应窗口爬坡器的目标、对抗用例、探测机制审计 JSR-107 符合性 →.claude/docs/jsr107-conformance.md审计发现分类 →.claude/docs/finding-taxonomy.md批量审计轮次与报告合并 →.claude/docs/audit-rounds.md、.claude/docs/audit-output.md。仓库中实际存在的 docs 文件包括audit-output.md、audit-rounds.md、design-decisions.md、finding-taxonomy.md、hill-climber.md、jsr107-conformance.md、research-foundations.md、synchronization.md、testing.md。其中wiki/adaptive-window.html是爬坡器面向人类读者的设计文档约 470 KB 的渲染产物内容即hill-climber.md前 6 节的散文版规范甚至明确建议 Agent 不要直接读取该 HTML而是读hill-climber.md源文档。扩展体系skills、agents 与 hooks技能skills.claude/skills/下按主题组织大量可复用技能CLAUDE.md对其做了分类说明评审类/review-change多层并行代码评审结合盲审、设计感知与回归模式匹配审计类/audit-*针对并发、正确性、性能的快照式深度分析如/audit-jmm线程安全、/audit-linearizability线性化、/audit-exception-safety异常路径、/audit-memory-retention内存泄漏、/audit-adversarial无领域上下文的敌意全量审查等二十余个方向并配有一张关注什么就运行哪个的审计选择表历史挖掘类/audit-temporal-walk逐提交正向遍历项目全部历史的重量级审计walker.pyverify.py耗时数小时数月或大版本前才运行一次模拟器类/sim-compare、/sim-analyze策略对比图表与 trace 特征分析驱逐质量工作流/climber-gate、/audit-regret、/climber-minimize、/audit-adaptivity关注正确代码的性能质量而非正确性本身——/climber-gate在每次WindowClimber改动后验证已知陷阱是否被破坏/audit-regret寻找仍会掉命中率的工作负载族/climber-minimize周期性检验每个算法步骤是否仍值得其复杂度。这些技能目录里带有配套脚本与规格如climber-gate下的gate.py、gen_*.pyaudit-regret下的regret.py、search.py、数十个 workload JSON 规格说明它们不是概念说明而是可实际执行的工作流。审计代理与钩子.claude/agents/auditor.md审计代理多轮执行分析 → 反思 → 评估者挑战 → 定向复审.claude/hooks/两个 bash 钩子——audit-report-guard.shSubagentStop 时校验审计报告格式与test-scope-guard.shPreToolUse 时拦截过大的测试范围配套测试脚本test-scope-guard.test.sh保证钩子自身行为正确.claude/settings.json定义权限白名单允许./gradlew *、git status/log/diff/blame/show、gh issue/pr/api/run/search等与钩子绑定。规范还约定审计输出写入.local/audits/model/skill-name.md按产出模型分目录另有shared目录存放跨模型协作文档该目录被 gitignore 但长期保留而跨会话的工作队列用LEDGER.md记录在.local/experiments/topic/下。模块划分与落地实践.claude/CLAUDE.md给出仓库顶层模块划分caffeine/ — Core cache library guava/ — Guava compatibility adapter jcache/ — JSR-107 JCache adapter simulator/ — Cache policy simulator另有examples/下的示例工程coalescing-bulkloader-reactor、graal-native、hibernate、indexable、resilience-failsafe、write-behind-rxjava与wiki/下的设计文档。对 Agent 而言一个典型的协作流程是读取AGENTS.md跳转到.claude/CLAUDE.md完整阅读根据任务涉及的路径扫描.claude/rules/*.md的pathsfrontmatter命中即读如改BoundedLocalCache.java则读concurrency.md与design-decisions.md按需查阅.claude/docs/中的深度文档如涉及并发则读synchronization.md用./gradlew :caffeine:test --tests Class.method之类的最小命令验证改动必要时运行专项测试套件与静态分析若涉及WindowClimber在提交前运行/climber-gate验证未破坏已知陷阱。这套体系的最终目的是让 AI Agent 以与人类贡献者相同的方式理解项目约定——先读规范、再按路径加载规则、用最小命令验证、用专项套件兜底从而在高性能、近最优缓存库这一对正确性与并发安全要求极高的代码库中可靠地完成分析、审计与修改任务。结语AGENTS.md虽然只有十几行却是整个 Caffeine 仓库 AI 协作体系的钥匙它定义了规范单点.claude/CLAUDE.md、规则按需加载.claude/rules/*.md与paths、文档按需参考.claude/docs/*.md三大机制。向下展开是覆盖构建测试、静态分析、并发约定、代码生成、专项测试、审计技能的一整套工程基础设施。对希望用 Agent 深入 Caffeine 源码的开发者来说从这份入口文档出发按路径加载规则、按主题查阅文档、用最小命令验证就能快速对齐这个项目的全部隐性约定——这套引导层 规范集中 按需加载的组织方式本身也值得其他追求 Agent 友好度的仓库借鉴。赞分享后端缓存抽象【免费下载链接】caffeineA high performance caching library for Java项目地址https://gitcode.com/gh_mirrors/ca/caffeine点击查看免费下载相关推荐AzerothCore 的 AI Agent 协作规范全解AGENTS.md 规则体系与仓库源码级解析AzerothCore 的 AI Agent 协作规范全解AGENTS.md 规则体系与仓库源码级解析 AzerothCore 是一个基于 C 的 MMO游戏开发后端CopilotKit 仓库协作规范解读从 Nx 单仓工作流到文档体系的 AGENTS.md 工程实践CopilotKit 仓库协作规范解读从 Nx 单仓工作流到文档体系的 AGENTS.md 工程实践 CopilotKit 的 AGENTS.md 是该仓库面人工智能AI AgentAgent 框架前端后端agent-browser 仓库的 AI 编码代理协作指南AGENTS.md 工程规范全解读agent browser 仓库的 AI 编码代理协作指南AGENTS.md 工程规范全解读 导读 本文围绕 agent browser面向 AI Agen浏览器控制CLIAI 应用GUI 自动化开发工具AI 技能MCP 服务上一篇百度ERNIE 4.5-VL开源280亿参数多模态模型如何重塑AI应用生态下一篇MASA模组汉化包5分钟解决英文界面难题建筑玩家必备工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考