yomiyasu 实战：用 Agent Skill 推敲代码评审反馈文——从分层架构指摘到自然日语表达-平芜编程栈

【免费下载链接】yomiyasu

AI生成の日本語を自然な日本語へ推敲するAgent Skill / Agent Skill for Refining AI-Generated Japanese into Natural Japanese

项目地址：https://gitcode.com/gh_mirrors/yo/yomiyasu

代码评审反馈是 AI 生成最容易"翻车"的文体之一：业务规则判定、SQL 与外部 API 调用混写在一个方法里，评审意见既要讲清架构问题，又要给出可执行的改造建议，还得分清"说明现状"与"提出要求"两种文句功能。yomiyasu 在 tests/corpus/yomiyasu_rewritten/07_code_review_sonnet_formal_bl.md 中留下了一段正式文体（formal）的推敲样本，本文以它为解剖对象，结合 SKILL.md 的转换原则与 scripts/build_corpus.py 的语料生成机制，完整还原"AI 生成文 → yomiyasu 推敲文"的改写过程，并延伸到服务层、仓储层、网关层的分层设计原理，帮助你既学会用 yomiyasu 处理此类文本，也理解评审意见背后的架构常识。

案例定位：语料库中的代码评审反馈样本

该样本属于仓库tests/corpus中"8 个实务场景 × 3 种文体"语料矩阵的第 07 号主题。在 scripts/build_corpus.py 中，该主题的生成提示词是：

サービス層にDBアクセスや外部API呼び出しのビジネスロジックが混在しているコードに対する、責務分離を促すコードレビューのフィードバックコメント（400字程度）を作成してください。

围绕同一主题，语料库保存了三个版本，形成完整的对照链：

目录	文件	角色
`tests/corpus/raw_ai`	07_code_review_sonnet_formal.md	未加约束的 AI 原始输出
`tests/corpus/blacklist_ai`	07_code_review_sonnet_formal.md	加入"禁用 AI 味词汇"指令后的输出
`tests/corpus/yomiyasu_rewritten`	07_code_review_sonnet_formal_bl.md	对 blacklist 版应用 yomiyasu 推敲的结果（本文关联文档）

文件名后缀_bl表示改写输入取自blacklist_ai，formal表示系统提示词要求"エンタープライズシステムのシニアアーキテクト。堅牢で形式的な文体"。这是理解整篇文章的坐标系：yomiyasu 处理的对象，恰恰是已经"被禁用词约束过"的 AI 输出，说明它的价值不在替换个别词汇，而在重构句法与文脉。

推敲后的目标文本（关联文档全文）

以下为yomiyasu_rewritten/07_code_review_sonnet_formal_bl.md的完整内容，是本文讨论的唯一主体：

本サービスクラスでは、業務ルールの判定、SQLの発行、外部APIの呼び出しを同じメソッドに書いています。この構成だと、業務ロジックを検証するためにDBや外部サービスを起動しなければならず、単体テストを書きにくくなります。外部APIの仕様やスキーマが変わるたびに、業務ロジックも修正する必要がある点も、保守上の問題です。永続化処理はリポジトリ層に、外部連携はゲートウェイ層に切り出し、サービス層はインターフェース経由でそれらを呼び出すように改めてください。こうすれば、モックを使って業務ロジックを単体テストできます。あわせて、トランザクション境界はサービス層で管理し、リトライやタイムアウトの制御は外部連携の実装側にまとめることを推奨します。

翻译并拆解其技术要点，这段评审反馈由三个层次组成：

现状指摘：服务类（Service クラス）的同一方法内混写了业务规则判定、SQL 发布、外部 API 调用三种职责；
后果分析：验证业务逻辑必须先启动 DB 和外部服务，导致单元测试难写；外部 API 规格或 Schema 每次变更都牵动业务逻辑修改，带来维护负担；
改造建议：持久化（永続化）处理迁往 Repository 层，外部协作（外部連携）迁往 Gateway 层，服务层通过接口（インターフェース）调用二者，从而可用 Mock 进行单元测试；同时推荐事务边界（トランザクション境界）留在服务层管理，重试与超时控制收拢到外部协作实现侧。

三版对比：yomiyasu 到底改了什么

将推敲结果与改写输入（blacklist 版）、未加约束的原始输出（raw 版）并排对照，能精确看出每个转换动作。

与 blacklist 版（改写输入）的对比

blacklist 版原文为：

本サービスクラスでは、業務ルールの判定、SQLの発行、外部APIの呼び出しが同一メソッド内に記述されています。この構成では、業務ロジックの検証にDBや外部サービスの起動が必要となり、単体テストが困難です。また、外部APIの仕様変更やスキーマ変更が、業務ロジックの修正を伴う点も保守上の課題です。永続化処理はリポジトリ層に、外部連携はゲートウェイ層に分離し、サービス層はインターフェース経由でそれらを呼び出す構成へ改めてください。この分離により、モックを用いた業務ロジックの単体テストが可能となります。あわせて、トランザクション境界はサービス層で管理し、リトライやタイムアウトの制御は外部連携の実装側へ集約することを推奨します。

逐处差异如下：

改写前（blacklist 版）	改写后（yomiyasu 版）	对应原则
記述されています（状态描述，被动）	書いています（动作描述，主动）	主述对应、动作主体明确
この構成では、〜となり、単体テストが困難です（名词化堆叠）	この構成だと、〜しなければならず、単体テストを書きにくくなります（动词谓语句）	サ変名詞の数珠つなぎを動詞述語へ戻す
仕様変更やスキーマ変更が、業務ロジックの修正を伴う	仕様やスキーマが変わるたびに、業務ロジックも修正する必要がある	条件·触发关系具体化
分離し、〜構成へ改めてください	切り出し、〜呼び出すように改めてください	动作具体化，避免抽象名词
この分離により、〜可能となります	こうすれば、モックを使って〜できます	因果连词收拢，去形式化
集約することを推奨します	まとめることを推奨します	比喩·生硬语平实化

与 raw 版（无约束 AI 输出）的对比

raw 版是未被任何约束干预的原始输出，结构上采用"三问题分列 + 提案"的展开方式，而 yomiyasu 版压缩为连续叙述。raw 版中"責務の分離の観点から三つの問題があります"这种只预告不落地的空泛句被直接消解；"依存性注入を採用すれば、テスト容易性と差し替え可能性も確保できます"这句锦上添花的承诺也被删除，因为原文并未要求写入 DI 的额外收益。这符合 SKILL.md 中"情報を勝手に足さない"（不自行添加原文没有的信息）的最高优先原则。

改写手法逐条解析：yomiyasu 七原则的落地

README.md 记录了 yomiyasu 的 7 条转换原则，本节以该样本逐条印证。

1. 主述·修饰·条件的点检

原句"業務ロジックを検証するためにDBや外部サービスを起動しなければならず"中，动作主是隐性的"测试者/开发者"。yomiyasu 通过"起動しなければならず"保留了原文"必要性"的言说强度，没有擅自补充"開発者は"这样的主语——因为原文并未明示主体。这与 SKILL.md 中"原文や提供文脈から分かる主体を必要な位置で示し、元にない担当者を創作しない"完全一致。

2. 文的功能与文体保持

这是本样本最精妙的一处。整段文本有两种文の働き（句子功能）：

说明型（现状·后果）：句末为"書いています""書きにくくなります""問題です""できます"；
要求/建议型（改造指令）：句末为"改めてください""推奨します"。

yomiyasu 完整保留了这种功能分层，没有把"説明"句改成"要求"句，也没有把"〜してください"的请求强度削弱为"〜しましょう"。对照 SKILL.md 中"文書の立場と文末"一节，代码评审反馈属于"勧め"（建议）立场，动作发出者是受评审的开发者，因此"改めてください"与"推奨します"的组合是立场正确的。

3. 拟人化整理

原文中"サービス層はインターフェース経由でそれらを呼び出す"是架构概念的动作描述，属于客观的系统行为叙述，而非给概念赋予意志的拟人化，因此 yomiyasu保留了"サービス層は〜呼び出す"的表述。这正是 SKILL.md 强调的边界："道具や仕組みの働きを客観的に述べている文はそのまま残します。"

4. 比喩を平易な言葉へ

blacklist 版中"集約する"（aggregate）一词带有抽象隐喻色彩，yomiyasu 改为"まとめる"（归拢），在保持"集中管理"含义的同时更口语化。类似的，"切り出し"（切出）取代"分離し"（分离），把架构动作从名词化状态还原为具体操作。这些都是 references/domains/business.md 中"比喩をふだんの言葉に直す"的典型应用。

5. 前置き·否定対比の役割確認

raw 版的"責務の分離の観点から三つの問題があります"属于预告性前置，yomiyasu 版直接删除，因为后续内容并未按"第一、第二、第三"展开（blacklist 版本就没有分列），删除后主张与比重不受影响。这与"前置きを削るのは、削っても主張や比重が変わらない場合だけ"的原则严格吻合。

6. 情報を勝手に足さない

最明显的验证是 raw 版末句"依存性注入を採用すれば、テスト容易性と差し替え可能性も確保できます"。改写输入（blacklist 版）中没有这一句，yomiyasu 版也没有补回。推敲过程没有把"通过接口调用"自行扩写成"采用依赖注入"，杜绝了越权添加信息。

7. 文長·読点·装飾の調整

对照 README.md 的"平均文長30〜45文字、1文の読点0〜2個"目安，本样本的单句长度适中：以"この構成だと、〜書きにくくなります"为例，全句约 45 字、1 个读点，处于推荐区间；"永続化処理はリポジトリ層に、外部連携はゲートウェイ層に切り出し、〜改めてください"通过成对的"〜は〜に"结构建立平行节奏，读点起的是对照分组作用而非装饰。全文没有出现 em dash、装饰性文末冒号与多余加粗，符合"装飾記号の排除"规则。

技术实质：这段评审反馈讲的分层架构是什么

要让这篇文章不只停留在"推敲"层面，还需把评审意见背后的工程原理讲透——这也是推敲结果质量的地基。

服务层混写为何有害

"业务规则判定 + SQL 发布 + 外部 API 调用"同处一个方法，意味着验证业务逻辑必须真实启动 DB 与外部服务。单元测试因此退化为集成测试：环境搭建成本高、执行慢、外部依赖抖动会导致测试不稳定。这正是语料主题生成词中"責務分離を促す"的指向。

Repository / Gateway / 接口三层拆解

Repository 层：负责永続化処理（SQL 发布、ORM 操作），把数据访问细节与业务规则隔离；
Gateway 层：负责外部連携（第三方 API 调用），把外部协议、Schema 变化圈定在网关实现内部；
服务层：只保留业务规则判定，通过接口（インターフェース）声明对 Repository 与 Gateway 的依赖，运行时注入具体实现。

这样拆分后，测试代码可以用 Mock 替身替换真实 Repository/Gateway，业务逻辑的单元测试不再触碰 DB 与外部网络。这也是该样本中"こうすれば、モックを使って業務ロジックを単体テストできます"的完整论证链条。

事务边界与重试/超时的归属

样本末句给出了两条关键推荐：

トランザクション境界はサービス層で管理：事务需要横跨多个仓储操作（多表更新、补偿逻辑），只有服务层能界定"一个业务用例"的边界，因此事务应开在服务层，而非埋在某个仓储方法内部；
リトライやタイムアウトの制御は外部連携の実装側にまとめる：重试策略（退避算法、最大次数）与超时阈值只与外部 API 的稳定性有关，属于 Gateway 的领域知识，收拢到外部协作实现侧，避免每个调用方各自实现导致策略漂移。

这两条建议在语料生成提示词中并未逐条给出，而是模型基于架构常识自然产出的；yomiyasu 的职责是保证这些技术要点以准确、自然的日语传达，而非发明或删改它们。

语料库的构建机制：这段文本从哪来

tests/corpus不是手写语料，而是由 scripts/build_corpus.py 通过 Claude CLI 按"8 主题 × 3 文体"矩阵程序化生成（生成前会删除旧文件，仓库只读使用时不运行）：

raw_ai：用RAW_PROMPT_PREFIX（要求只输出正文）+ 各主题提示词直接生成；
blacklist_ai：在提示词末尾追加BLACKLIST_PROMPT_SUFFIX，禁止使用"手触り""解像度""地味に効く""静かに壊れる""時間を溶かす"等 AI 味词汇（scripts/build_corpus.py）；
yomiyasu_rewritten：将 raw 版与 blacklist 版分别送入YOMIYASU_REWRITE_PROMPT（scripts/build_corpus.py），该提示词要求复现"谁/什么/怎么"的统语结构、把比喻动词展开为字面技术处置、剥除无据加粗、合并多余列表、消除否定对比、排除装饰符号等，blacklist 版的输出以_bl后缀命名。

由此可知，本文关联文档是"禁用词约束输出 × yomiyasu 推敲"双阶段的结果，它验证的是 yomiyasu 在词汇已被约束时仍能改善句法与文脉——这正是 README 所述"従来のアプローチ（禁止語の置き換え）が抱えていた限界"的对照实验。

验证工具链：如何客观检查这类推敲结果

yomiyasu 仓库自带两个检查脚本，可作为评审反馈文推敲后的客观度量手段。

静态检查：scripts/yomiyasu_lint.py

执行方式（仓库只读，路径以仓库根目录为基准）：

python3 scripts/yomiyasu_lint.py README.md python3 scripts/yomiyasu_lint.py article.md --strict python3 scripts/yomiyasu_lint.py article.md --json

其检查项包括：AI 味词汇（SLOP_WORDS）、比喻动词模式（如"静かに壊れる""〜側に倒す""時間を溶かす"，见 METAPHOR_VERB_PATTERNS）、前置填充词（"重要なのは""いかがでしたでしょうか"）、否定对比（"AではなくB"）、同一文末三连、加粗频率（每千字 2.0 以下为推荐、3.0 以上为警告）与列表比率（15% 以下推荐、25% 以上警告）。对本文样本而言，推敲结果不含上述任何模式，理论上可得到 [PASS] 判定。需要强调的是，scripts/yomiyasu_lint.py 文档串明确声明：检测结果是复查候选，[PASS] 只代表无规则指摘，不代表自然、意味保持或绝对可读。

差分检查：scripts/yomiyasu_diff.py

用于对照改写前后文本，核查语词增减、文末类型与立场（勧め/決まり/説明）变化：

python3 scripts/yomiyasu_diff.py 元の文.md 書き直した文.md --stance=説明 python3 scripts/yomiyasu_diff.py --endings 対象文.md

针对本文案例，可指定--stance=勧め（建议立场）运行，核对"改めてください""推奨します"等要求型文末是否被误改为说明型。脚本输出同样只是候选清单，最终以人读判断为准。

使用边界与正确姿势

最后必须交代语料的适用前提，避免误用：

evals/comparison_benchmark.md 明确声明，语料中的"適用後"文本是过去验证时保存的输出，不是当前版本的实际运行结果，也不作为现行"意味保持规则"的合格例；当时代的完整提示上下文未保留，个别"適用後"文包含仅凭前文无法确定的条件或步骤；
静态检查无指摘 ≠ 语义保真。语料的定位是"记录"而非"及格卷"，推敲结果的最终质量须以 SKILL.md 的"意味の保持（主張・比重・言い切りの強さ・文の働き）"四点为准绳人工复核；
本文关联文档可视为一份教学型样本：它展示的是 yomiyasu 原则在"代码评审反馈 + 正式文体 + 已约束词汇"组合下的理想输出形态，实际使用时请结合 references/domains/business.md 的业务文书写规范（责任主体明确、条件与结果一一对应、比喩平实化）进行同款推敲。

通过这一份样本，你可以同时掌握三件事：一是 yomiyasu 处理实务文书的完整手法清单，二是服务层/仓储层/网关层拆分与事务边界归属的架构常识，三是用仓库自带工具客观核验推敲结果的流程——这套组合拳可以直接迁移到你的技术评审与代码审查写作中。