Actual Budget 代码评审规范完全指南基于 code-review-rubric 的 PR 审查实践【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual导读本文围绕 Actual Budgetactualbudget/actual一款本地优先的个人财务管理应用TypeScript React 编写代码库中的评审清单文档 code-review-rubric.md系统讲解该仓库在 PR 代码审查中必须遵守的硬性规则、类型与 React 模式、导入规范、国际化要求、财务数字排版、测试策略、提交规范及重点审查路径。读完本文你将获得一份可直接投入实际审查工作的检查表并理解每条规则背后的仓库源码依据——无论是人工评审还是 AI Agent 执行 review都能据此快速定位问题、给出可粘贴的修复建议。文档定位一份为持续审查而生的浓缩清单rubric 文档明确说明其来源由CODE_REVIEW_GUIDELINES.md、AGENTS.md和.github/agents/pr-and-commit-rules.md三份文档蒸馏而成目的是让评审者在审查中途不必反复阅读数百行原始规范即可保持流畅。当评审者命中某条规则时应按照节名如 Type assertions引用规则来源方便用户回溯原始文档。三者分工如下来源文档职责CODE_REVIEW_GUIDELINES.mdLLM Agent 执行代码评审的具体准则涵盖设置泛滥、严格模式豁免、类型断言、any/unknown、i18n、测试 Mock、财务数字排版等AGENTS.md面向 AI Agent 的完整开发指南项目概览、命令、架构、代码风格与约定、常见任务排查.github/agents/pr-and-commit-rules.mdAI 生成的 PR/提交必须遵守的规则[AI]前缀、PR 模板、issue 与评论前缀等此外这份 rubric 被 .claude/skills/review-actual-pr/SKILL.md 引用为审查 diff 之前必读的浓缩规则集。在该 skill 的审查工作流中发现分为三档Criticalbug、安全问题、类型/构建破坏、数据丢失风险、Important违反仓库规则和Suggestion清晰度、命名、死代码、可提取的重复模式。硬性拒绝项Hard rejections以下条目来自 CODE_REVIEW_GUIDELINES.md除非 PR 中带有成文的理由说明否则不可协商为 UI 微调新增设置项Important。Actual Budget 刻意抵制设置膨胀settings bloat。如果 PR 为某个本可用主题/设计 token 表达的内容新增用户可见的开关或偏好项应标记为 Important并提出基于主题的替代方案。原始文档的立场是优先硬编码值或基于主题的解决方案评估设置是否对用户提供有意义的价值并检查是否与 Actual 的设计准则一致。新增ts-strict-ignore注释Important若掩盖真实类型错误则为 Critical。项目通过typescript-strict-plugin执行严格类型检查新增豁免会削弱类型安全。应建议修复底层类型问题。注意 AGENTS.md 明确说明新文件必须类型严格type-strict不得添加// ts-strict-ignore存量文件被祖父条款豁免。从源码看仓库中确实存在历史遗留的豁免点例如 FixedSizeList.tsx、ManageRules.tsx、Modals.tsx 等文件均含有ts-strict-ignore——这正是存量豁免、新增禁止策略的体现。新增eslint-disable或oxlint-disable注释。逻辑同上规则的存在有其理由应提出满足规则的修复方案而非抑制规则。仓库当前同时使用 oxlint配置见 .oxlintrc.json与自定义的actual/*规则集。代码中的密钥/凭据Critical。永远如此无例外。TypeScript 类型规则来自 AGENTS.md CODE_REVIEW_GUIDELINES.mdrubric 将类型层面的约定归纳为五条每条都能在仓库中找到对应实践优先type而非interface。禁止enum——使用对象映射。仓库的 eslint-plugin-actual 中就有no-enum规则在 lint 层面强制这一约定。禁止无理由的any/unknown。在提出新类型之前先到 packages/loot-core/src/types/含models/子目录、prefs.ts、server-handlers.ts等查找是否已存在合适类型。loot-core是整个应用的类型定义中心业务模型、处理器签名与偏好项类型都在此集中维护。优先x satisfies SomeType而非x as SomeType。satisfies能保留更精确的推断并在编译期捕获类型不匹配唯一例外是真正的运行时类型守卫——此时必须加注释说明为何as是安全的。CODE_REVIEW_GUIDELINES.md 对该例外有完整表述。禁止React.FC、React.FunctionComponent及泛化的React.*用法。应使用具名导入并直接标注 props 类型。这与 AGENTS.md 中React.* → 具名导入的迁移方向一致——仓库正在逐步清除历史遗留的React.*模式。React 模式React Compiler 已开启。AGENTS.md 指出desktop-client、component-library等包含 React 代码的应用包均启用了babel-plugin-react-compiler编译器会自动记忆化组件体。因此除非某个未编译的依赖确实需要稳定引用stable identity否则不要手动添加useCallback/useMemo/React.memo多余的记忆化应标记为 Suggestion。使用路由器的Link而非a标签。仓库的 eslint 插件提供了 no-anchor-tag.js 规则来强制这一点。Hooks 必须来自项目自己的封装useNavigate等来自 src/hooks例如其中的 useNavigate.ts该目录下还有 100 个业务 hooks而不是react-router-domuseDispatch、useSelector、useStore来自src/redux而不是react-redux。避免在组件内部定义嵌套组件会导致引用不稳定。导入规范UUID 导入必须使用import { v4 as uuidv4 } from uuid;绝不允许默认导入uuid。禁止直接导入颜色一律使用主题。颜色必须经由主题系统设计 token消费packages/component-library/src/themes/下的dark.css、light.css、midnight.css、palette.css是主题变量的实际载体。loot-core内禁止actual-app/web/*导入。依赖方向必须保持单向核心逻辑包不得反向引用 UI 包。导入顺序React → 内置模块 → 外部依赖 → actual 内部包loot-core、actual-app/components→ 父级 → 同级 → index。各组之间保留空行。该规则由 lint 强制违反时标记为 Suggestion。这与 AGENTS.md 中绝对导入、平台特定导出经 package.json exports 解析的整体约定配合。国际化i18n所有用户可见字符串必须翻译。优先使用Trans组件而非t()函数。自定义 ESLint 规则 actual/no-untranslated-strings 能捕获大多数遗漏但评审者仍应人工抽查明显漏网之鱼例如ButtonSave/Button这类硬编码文本。配套规则 prefer-trans-over-t.js 在 lint 层强制优先 Trans 组件桌面端应用的实际文案则通过 desktop-client 的 i18n 体系 管理修改文案后可用yarn generate:i18n重新生成语言文件见 AGENTS.md。财务排版Financial typography独立的财务数字必须包裹在FinancialText中或在无法包裹时直接应用styles.tnum。等宽数字tabular figures对预算类 UI 的可读性至关重要——金额在列中对齐才不会跳动。仓库中的实际实现位于 FinancialText.tsx评审时可将该组件作为标准答案对照设计 token 与排版基准则可参考 component-library 的 tokens.ts。测试规范最小化 Mock单元测试与组件测试优先使用真实实现real implementations而非桩stubs。仅对外部网络、单元测试环境下的文件系统等确实不切实际的依赖进行 Mock。过度 Mock 会使测试脆弱且不可靠见 CODE_REVIEW_GUIDELINES.md。Vitest 全局变量describe、it、expect、beforeEach直接可用无需显式导入。这与 AGENTS.md 的说明一致Vitest 是单元测试运行器测试文件采用.test.ts/.test.tsx/.spec.js命名。E2E 测试位于 packages/desktop-client/e2e/其中page-models/下的页面模型应复用而非重复编写移动端测试使用.mobile.test.ts后缀视觉回归快照存放在各*-snapshots/目录。平台特定代码非平台代码禁止直接.api/.electron导入。平台解析在构建期通过loot-core的 package.jsonexports条件导出完成node 与 browser 各有实现。如果直接 import 另一平台的模块会破坏这一构建期解耦。Commit / PR 规则来自 pr-and-commit-rules.md以下规则对 AI 生成的 PR 是强制性的评审时应逐条核对并将遗漏标记为Important提交信息必须以[AI]前缀开头。PR 标题必须以[AI]前缀开头AI generated标签会基于此前缀自动应用无需单独验证。PR 模板不得填写除非人类明确要求填写——此时必须使用中文填写。模板本体位于 .github/PULL_REQUEST_TEMPLATE.md默认情况下应原样保留空白与占位注释。禁止--no-verify、--no-gpg-sign、强推 main 分支及任何破坏性 git 操作。补充背景根据 .github/agents/pr-and-commit-rules.mdAgent 还不得创建 GitHub issue且所有发往 GitHub 的评论/评审/issue 内容必须以 前缀标记——这些虽非评审必须验证项但属于同一规则体系。需要额外重点审查的文件与路径rubric 明确指出以下区域在评审中需要额外投入并给出了默认严重级别packages/loot-core/src/server/migrations/——数据库模式迁移。必须幂等idempotent任何不幂等、或在没有回填backfill方案的情况下删除/重写数据的迁移默认按Critical处理。该目录中既有.sql也有.js迁移如1722717601000_reports_move_selected_categories.js说明历史迁移包含程序化数据搬迁评审时要特别关注这类带逻辑的迁移。packages/loot-core/src/server/budget/——预算数学。这里的 off-by-one 或舍入错误会直接在用户的报表中造成金钱损失必须逐行细读。packages/desktop-client/src/components/budget/——主 UI 面。重渲染模式与 selector 使用在此处至关重要叠加 React Compiler 的语义记忆化取舍尤其需要谨慎。packages/sync-server/——服务端。CRDT / 同步变更需仔细检查排序与竞态条件核心 CRDT 实现在 packages/crdt/src/crdt/。[packages/desktop-client/e2e/ 下的*-snapshots/目录——VRT 快照。如果 PR 更新了这些快照diff 本身就是评审对象打开新的 PNG确认视觉变化与 PR 声明的意图一致。评审时可以跳过的内容生成文件packages/component-library/src/icons/下的图标组件是自动生成的不需要评审AGENTS.md 同样强调不要手动编辑。构建产物*/dist、*/build、*/lib-dist本就不应出现在 PR 中。翻译源文件机器生成的翻译无需逐字评审。评审输出的格式要求rubric 的最后一段对评审意见本身提出了硬性要求——每条 finding 必须包含path:line或path:line-line范围取自 diff hunk 而非估算12 句问题描述具体的建议修改——替换代码或 unified-diff 片段可直接粘贴。不允许给出考虑重构一下这类模糊建议要给出重构本身。在 .claude/skills/review-actual-pr/SKILL.md 的完整工作流中这一要求被进一步强化报告必须包含 Head SHA 与 Reviewed 时间戳用于重跑时检测过期且每档Critical / Important / Suggestions即使零发现也要显式声明no Critical issues found让用户确信该维度已被检查。总结把 rubric 变成日常审查习惯这份 rubric 的价值在于它把三个来源文档评审准则、Agent 开发指南、提交规则压成了一张单页检查表。实际操作时建议按以下顺序过一遍先扫硬性拒绝项设置膨胀、严格模式豁免、lint 抑制、凭据再按类型 → React → 导入 → i18n → 财务排版逐层审代码风格随后核对测试质量与平台隔离最后确认提交/PR 元数据合规并针对迁移、预算数学、预算 UI、sync-server、VRT 快照五个高风险区域做重点深挖。最终每条意见都带上path:line与可粘贴的修复代码——这正是 Actual Budget 仓库对高质量代码评审的完整定义。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Actual Budget 代码评审规范完全指南：基于 code-review-rubric 的 PR 审查实践
Actual Budget 代码评审规范完全指南基于 code-review-rubric 的 PR 审查实践【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual导读本文围绕 Actual Budgetactualbudget/actual一款本地优先的个人财务管理应用TypeScript React 编写代码库中的评审清单文档 code-review-rubric.md系统讲解该仓库在 PR 代码审查中必须遵守的硬性规则、类型与 React 模式、导入规范、国际化要求、财务数字排版、测试策略、提交规范及重点审查路径。读完本文你将获得一份可直接投入实际审查工作的检查表并理解每条规则背后的仓库源码依据——无论是人工评审还是 AI Agent 执行 review都能据此快速定位问题、给出可粘贴的修复建议。文档定位一份为持续审查而生的浓缩清单rubric 文档明确说明其来源由CODE_REVIEW_GUIDELINES.md、AGENTS.md和.github/agents/pr-and-commit-rules.md三份文档蒸馏而成目的是让评审者在审查中途不必反复阅读数百行原始规范即可保持流畅。当评审者命中某条规则时应按照节名如 Type assertions引用规则来源方便用户回溯原始文档。三者分工如下来源文档职责CODE_REVIEW_GUIDELINES.mdLLM Agent 执行代码评审的具体准则涵盖设置泛滥、严格模式豁免、类型断言、any/unknown、i18n、测试 Mock、财务数字排版等AGENTS.md面向 AI Agent 的完整开发指南项目概览、命令、架构、代码风格与约定、常见任务排查.github/agents/pr-and-commit-rules.mdAI 生成的 PR/提交必须遵守的规则[AI]前缀、PR 模板、issue 与评论前缀等此外这份 rubric 被 .claude/skills/review-actual-pr/SKILL.md 引用为审查 diff 之前必读的浓缩规则集。在该 skill 的审查工作流中发现分为三档Criticalbug、安全问题、类型/构建破坏、数据丢失风险、Important违反仓库规则和Suggestion清晰度、命名、死代码、可提取的重复模式。硬性拒绝项Hard rejections以下条目来自 CODE_REVIEW_GUIDELINES.md除非 PR 中带有成文的理由说明否则不可协商为 UI 微调新增设置项Important。Actual Budget 刻意抵制设置膨胀settings bloat。如果 PR 为某个本可用主题/设计 token 表达的内容新增用户可见的开关或偏好项应标记为 Important并提出基于主题的替代方案。原始文档的立场是优先硬编码值或基于主题的解决方案评估设置是否对用户提供有意义的价值并检查是否与 Actual 的设计准则一致。新增ts-strict-ignore注释Important若掩盖真实类型错误则为 Critical。项目通过typescript-strict-plugin执行严格类型检查新增豁免会削弱类型安全。应建议修复底层类型问题。注意 AGENTS.md 明确说明新文件必须类型严格type-strict不得添加// ts-strict-ignore存量文件被祖父条款豁免。从源码看仓库中确实存在历史遗留的豁免点例如 FixedSizeList.tsx、ManageRules.tsx、Modals.tsx 等文件均含有ts-strict-ignore——这正是存量豁免、新增禁止策略的体现。新增eslint-disable或oxlint-disable注释。逻辑同上规则的存在有其理由应提出满足规则的修复方案而非抑制规则。仓库当前同时使用 oxlint配置见 .oxlintrc.json与自定义的actual/*规则集。代码中的密钥/凭据Critical。永远如此无例外。TypeScript 类型规则来自 AGENTS.md CODE_REVIEW_GUIDELINES.mdrubric 将类型层面的约定归纳为五条每条都能在仓库中找到对应实践优先type而非interface。禁止enum——使用对象映射。仓库的 eslint-plugin-actual 中就有no-enum规则在 lint 层面强制这一约定。禁止无理由的any/unknown。在提出新类型之前先到 packages/loot-core/src/types/含models/子目录、prefs.ts、server-handlers.ts等查找是否已存在合适类型。loot-core是整个应用的类型定义中心业务模型、处理器签名与偏好项类型都在此集中维护。优先x satisfies SomeType而非x as SomeType。satisfies能保留更精确的推断并在编译期捕获类型不匹配唯一例外是真正的运行时类型守卫——此时必须加注释说明为何as是安全的。CODE_REVIEW_GUIDELINES.md 对该例外有完整表述。禁止React.FC、React.FunctionComponent及泛化的React.*用法。应使用具名导入并直接标注 props 类型。这与 AGENTS.md 中React.* → 具名导入的迁移方向一致——仓库正在逐步清除历史遗留的React.*模式。React 模式React Compiler 已开启。AGENTS.md 指出desktop-client、component-library等包含 React 代码的应用包均启用了babel-plugin-react-compiler编译器会自动记忆化组件体。因此除非某个未编译的依赖确实需要稳定引用stable identity否则不要手动添加useCallback/useMemo/React.memo多余的记忆化应标记为 Suggestion。使用路由器的Link而非a标签。仓库的 eslint 插件提供了 no-anchor-tag.js 规则来强制这一点。Hooks 必须来自项目自己的封装useNavigate等来自 src/hooks例如其中的 useNavigate.ts该目录下还有 100 个业务 hooks而不是react-router-domuseDispatch、useSelector、useStore来自src/redux而不是react-redux。避免在组件内部定义嵌套组件会导致引用不稳定。导入规范UUID 导入必须使用import { v4 as uuidv4 } from uuid;绝不允许默认导入uuid。禁止直接导入颜色一律使用主题。颜色必须经由主题系统设计 token消费packages/component-library/src/themes/下的dark.css、light.css、midnight.css、palette.css是主题变量的实际载体。loot-core内禁止actual-app/web/*导入。依赖方向必须保持单向核心逻辑包不得反向引用 UI 包。导入顺序React → 内置模块 → 外部依赖 → actual 内部包loot-core、actual-app/components→ 父级 → 同级 → index。各组之间保留空行。该规则由 lint 强制违反时标记为 Suggestion。这与 AGENTS.md 中绝对导入、平台特定导出经 package.json exports 解析的整体约定配合。国际化i18n所有用户可见字符串必须翻译。优先使用Trans组件而非t()函数。自定义 ESLint 规则 actual/no-untranslated-strings 能捕获大多数遗漏但评审者仍应人工抽查明显漏网之鱼例如ButtonSave/Button这类硬编码文本。配套规则 prefer-trans-over-t.js 在 lint 层强制优先 Trans 组件桌面端应用的实际文案则通过 desktop-client 的 i18n 体系 管理修改文案后可用yarn generate:i18n重新生成语言文件见 AGENTS.md。财务排版Financial typography独立的财务数字必须包裹在FinancialText中或在无法包裹时直接应用styles.tnum。等宽数字tabular figures对预算类 UI 的可读性至关重要——金额在列中对齐才不会跳动。仓库中的实际实现位于 FinancialText.tsx评审时可将该组件作为标准答案对照设计 token 与排版基准则可参考 component-library 的 tokens.ts。测试规范最小化 Mock单元测试与组件测试优先使用真实实现real implementations而非桩stubs。仅对外部网络、单元测试环境下的文件系统等确实不切实际的依赖进行 Mock。过度 Mock 会使测试脆弱且不可靠见 CODE_REVIEW_GUIDELINES.md。Vitest 全局变量describe、it、expect、beforeEach直接可用无需显式导入。这与 AGENTS.md 的说明一致Vitest 是单元测试运行器测试文件采用.test.ts/.test.tsx/.spec.js命名。E2E 测试位于 packages/desktop-client/e2e/其中page-models/下的页面模型应复用而非重复编写移动端测试使用.mobile.test.ts后缀视觉回归快照存放在各*-snapshots/目录。平台特定代码非平台代码禁止直接.api/.electron导入。平台解析在构建期通过loot-core的 package.jsonexports条件导出完成node 与 browser 各有实现。如果直接 import 另一平台的模块会破坏这一构建期解耦。Commit / PR 规则来自 pr-and-commit-rules.md以下规则对 AI 生成的 PR 是强制性的评审时应逐条核对并将遗漏标记为Important提交信息必须以[AI]前缀开头。PR 标题必须以[AI]前缀开头AI generated标签会基于此前缀自动应用无需单独验证。PR 模板不得填写除非人类明确要求填写——此时必须使用中文填写。模板本体位于 .github/PULL_REQUEST_TEMPLATE.md默认情况下应原样保留空白与占位注释。禁止--no-verify、--no-gpg-sign、强推 main 分支及任何破坏性 git 操作。补充背景根据 .github/agents/pr-and-commit-rules.mdAgent 还不得创建 GitHub issue且所有发往 GitHub 的评论/评审/issue 内容必须以 前缀标记——这些虽非评审必须验证项但属于同一规则体系。需要额外重点审查的文件与路径rubric 明确指出以下区域在评审中需要额外投入并给出了默认严重级别packages/loot-core/src/server/migrations/——数据库模式迁移。必须幂等idempotent任何不幂等、或在没有回填backfill方案的情况下删除/重写数据的迁移默认按Critical处理。该目录中既有.sql也有.js迁移如1722717601000_reports_move_selected_categories.js说明历史迁移包含程序化数据搬迁评审时要特别关注这类带逻辑的迁移。packages/loot-core/src/server/budget/——预算数学。这里的 off-by-one 或舍入错误会直接在用户的报表中造成金钱损失必须逐行细读。packages/desktop-client/src/components/budget/——主 UI 面。重渲染模式与 selector 使用在此处至关重要叠加 React Compiler 的语义记忆化取舍尤其需要谨慎。packages/sync-server/——服务端。CRDT / 同步变更需仔细检查排序与竞态条件核心 CRDT 实现在 packages/crdt/src/crdt/。[packages/desktop-client/e2e/ 下的*-snapshots/目录——VRT 快照。如果 PR 更新了这些快照diff 本身就是评审对象打开新的 PNG确认视觉变化与 PR 声明的意图一致。评审时可以跳过的内容生成文件packages/component-library/src/icons/下的图标组件是自动生成的不需要评审AGENTS.md 同样强调不要手动编辑。构建产物*/dist、*/build、*/lib-dist本就不应出现在 PR 中。翻译源文件机器生成的翻译无需逐字评审。评审输出的格式要求rubric 的最后一段对评审意见本身提出了硬性要求——每条 finding 必须包含path:line或path:line-line范围取自 diff hunk 而非估算12 句问题描述具体的建议修改——替换代码或 unified-diff 片段可直接粘贴。不允许给出考虑重构一下这类模糊建议要给出重构本身。在 .claude/skills/review-actual-pr/SKILL.md 的完整工作流中这一要求被进一步强化报告必须包含 Head SHA 与 Reviewed 时间戳用于重跑时检测过期且每档Critical / Important / Suggestions即使零发现也要显式声明no Critical issues found让用户确信该维度已被检查。总结把 rubric 变成日常审查习惯这份 rubric 的价值在于它把三个来源文档评审准则、Agent 开发指南、提交规则压成了一张单页检查表。实际操作时建议按以下顺序过一遍先扫硬性拒绝项设置膨胀、严格模式豁免、lint 抑制、凭据再按类型 → React → 导入 → i18n → 财务排版逐层审代码风格随后核对测试质量与平台隔离最后确认提交/PR 元数据合规并针对迁移、预算数学、预算 UI、sync-server、VRT 快照五个高风险区域做重点深挖。最终每条意见都带上path:line与可粘贴的修复代码——这正是 Actual Budget 仓库对高质量代码评审的完整定义。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考