始终使用英语进行沟通和工作。在开始开发之前检查项目根目录是否存在PRD.md。如果存在在整个开发过程中阅读并遵循其中定义的需求。重要始终优先使用 Rust 原生实现。避免不必要的外部依赖尽可能利用 Rust 标准库。只有在有明确、合理的需求时才使用第三方 crate。重要遵循测试驱动开发TDD。详细规则请参见下面的**测试TDD**部分。重要在开始任何任务之前阅读并遵循METHODOLOGY.md。在编辑CLAUDE.md时使用最少的词汇和句子来传达 100% 的含义。完成每个计划中的任务后运行测试并提交然后才能继续下一个任务。如果更改对运行时行为没有影响例如文档、注释、CI 配置则跳过测试。对运行时配置文件YAML、JSON 等会被代码读取的文件的更改仍然必须触发测试。在任何代码更改功能添加、错误修复、重构、PR 合并之后检查README.md是否需要更新。如果项目描述、用法、设置、架构或 API 发生更改请使用清晰简洁的语言更新README.md。保持最小化——只记录用户需要知道的内容。测试 (TDD)先编写测试。遵循红-绿-重构(1) 失败的测试(2) 最少的代码使其通过(3) 重构。在测试中使用真实世界的场景和真实数据。优先使用实际用例而不是琐碎/刻意的例子。切勿过度拟合测试。实现必须解决通用问题而不仅仅是特定的测试用例。不允许硬编码返回值、不允许输入匹配条件、不允许只处理测试值的逻辑。使用三角测量——当伪造/硬编码的实现通过时添加不同输入的测试以强制泛化。测试行为而不是实现。断言可观察的结果而不是内部细节——测试必须在重构后仍然有效。每个新功能或错误修复都必须有相应的测试。优化测试执行速度。并行运行独立的测试。使用cargo test的默认并行性。保持每个测试隔离——无共享可变状态——以便并行执行是安全的。对于 I/O 密集型测试网络、文件优先使用异步或使用 mock 来避免阻塞。对于 CPU 密集型测试使用多线程并行。如果完整测试套件超过 30 秒进行调查将较慢的集成测试与快速单元测试分离先运行单元测试以获得快速反馈。无运行时影响时跳过测试。在 CI/CD 中使用路径过滤器仅在修改源代码、测试文件或运行时配置文件时触发测试。非运行时更改文档、README、.md、CI 流水线配置不应触发测试运行。日志记录在关键决策点、状态转换和外部调用处添加结构化日志——而不是每一行。仅凭日志应能揭示执行流程和根本原因。包含上下文请求/关联 ID、输入参数、耗时和结果成功/失败及原因。使用适当的日志级别error!用于需要采取行动的故障warn!用于可恢复的问题info!用于业务事件debug!/trace!用于开发诊断。使用tracingcrate 进行结构化、异步安全的日志记录。优先使用tracing::instrument进行自动 span 创建。切勿记录敏感数据凭证、令牌、PII。应对其进行屏蔽或省略。避免在热路径中过度记录——日志记录不得明显影响性能或增加延迟。命名名称必须是自描述的——无需阅读周围代码即可理解。避免使用晦涩的缩写proc、mgr、tmp。优先考虑清晰度而非简洁性但不要过度冗长。user_emailecalculate_shipping_costcalc。布尔值应读作是/否问题is_valid、has_permission、should_retry。函数/方法应描述操作和目标parse_config、send_notification、validate_input。类型优先使用显式类型注解而非类型推断。始终为函数签名参数和返回类型添加注解。当变量类型从赋值中不明显时为变量添加注解。使用 newtype 来强制执行领域语义例如使用struct Emu(f64)而不是裸f64。注释解释原因而不是内容。代码已经显示了它做了什么——注释应捕捉意图、约束和非显而易见的决策。注释业务规则、变通方法和为什么采用这种方法而不是显而易见的方法——这些是从代码本身无法推断出的背景信息。使用TODO(reason)或FIXME(reason)标记已知限制——始终包含原因而不仅仅是内容。当代码更改时删除注释——过时的注释比没有注释更糟糕。参考项目当面临设计决策或实现挑战时首先检查是否存在references/INDEX.md并找到相关的参考项目。如果references/中不存在相关项目请在网上搜索解决类似问题的维护良好的开源项目。搜索所有语言——架构模式可以跨语言迁移。当发现新的有用项目且references/存在时将其添加到references/INDEX.md并创建相应的详细信息文件。将详细信息文件保持在 50 行以内。在应用参考项目的模式时引用是哪个参考项目启发了您的方法。保密性切勿在提交消息、PR 标题/描述、问题评论或任何公开文本中提及tests/classified_fixtures/的内容文件名、路径、公司名称、个人姓名、文档标题。使用通用引用代替“机密测试夹具”、“内部测试文档”、基准真值 PDF等。Git 配置所有提交必须使用本地 git 配置user.name和user.email。在提交前使用git config user.name和git config user.email进行验证。所有提交必须包含Signed-off-by行始终使用git commit -s。Signed-off-by名称必须与提交作者匹配。分支与 PR 工作流所有更改都通过拉取请求进行。不允许直接提交到main。分支命名类型/简短描述例如feat/add-parser、fix/table-bug。一个分支 一个聚焦的工作单元。对所有分支工作使用 git worktrees。不要在主仓库中使用git checkout/git switch。创建git worktree add ../仓库名-分支名 -b 类型/简短描述在 worktree 内工作和推送。不要在任务完成后立即删除 worktree——仅在新工作开始或用户确认后删除。PR 合并流程按顺序执行所有步骤如果 PR 描述为空或不清晰通过gh pr edit重写。包括更改了什么、为什么更改、主要更改和相关背景。交叉引用相关 issuegh issue list。使用 “Related: #N”——除非另有指示否则避免使用自动关闭关键字。检查冲突。如果main有进展根据需要变基/合并。等待 CI 通过gh pr checks 编号 --watch。如果测试失败则中止。通过gh pr diff 编号进行最终代码审查——检查调试语句、硬编码路径、凭据、未使用的导入。合并gh pr merge 编号 --merge。切勿使用--delete-branchworktree 依赖于该分支。返回主仓库执行git pull同步。删除 worktreegit worktree remove ../仓库名-分支名删除本地分支git branch -d 分支名删除远程分支git push origin --delete 分支名MSRV 策略 — 6 个月滚动最低版本本项目遵循6 个月滚动 MSRV 策略与 tokio 和其他主要 crate 保持一致Cargo.toml中的rust-version必须目标指向至少 6 个月前发布的 Rust 稳定版Rust 稳定版每 6 周发布一次——具体日期请查阅 releases.rs当较新的 Rust 版本超过 6 个月阈值时允许但不要求更新 MSRV——仅当较新的语言特性或依赖项要求时才升级下限MSRV 绝不能低于Cargo.toml中edition要求的最低版本edition 2024 Rust 1.85在任何 MSRV 变更之前验证未使用目标版本以上的专属语言特性或 API确认所有依赖项都能在目标版本上编译使用目标工具链执行cargo check或检查依赖项 MSRV 元数据更新 CI 矩阵以包含新的 MSRV 版本视觉对比工作流在将 PDF 输出与基准真值机密测试夹具进行比较时运行cargo test -p office2pdf --test artifact_generator -- --ignored --nocapture生成产物。读取tests/classified_fixtures/_work/report.json——包含每个文件的页数、文本长度和 PNG 路径。识别最差文件页数不匹配、文本长度差异大、转换错误。对于最差文件使用读取工具查看tests/classified_fixtures/_work/work_dir/中的 PNG 图片output-*.png— office2pdf 输出渲染的页面gt-*.png— 基准真值 PDF 渲染的页面output.txt/gt.txt— 提取的文本直观地比较输出和 GT 的 PNG 图片以识别特定的渲染差异布局、字体、表格、图片、边距、分页等。对于 macOS 上用户提供的 DOCX/XLSX/PPTX 文件如果该文件类型有可用的 Word/Excel/PowerPoint则首先从原生 Microsoft 应用程序导出 PDF然后再进行推测比较。通过 TDD 修复解析器/代码生成器中的根本原因。优先考虑能改进多个文件的高杠杆修复。发布流程当要求发布时始终执行GitHub Release 和 crates.io 发布版本升级— 创建一个 PRchore/publish-版本号该 PR 在crates/office2pdf/Cargo.toml和crates/office2pdf-cli/Cargo.toml中升级version并更新 CLI 的office2pdf依赖版本。通过标准 PR 工作流合并。GitHub Release—gh release create v版本号包含更新日志和贡献者部分。使用git log 上一标签..HEAD --format%an | sort -u查找贡献者。列出每个贡献者并附上其 GitHub 个人资料链接。crates.io 发布— 先发布库再发布 CLIcargo publish -p office2pdfcargo publish -p office2pdf-cli标签对齐— 确保 GitHub 发布标签v版本号与 Cargo.toml 中的版本一致。