Restructure v2-v3, rewrite placeholders, polish metadata #20
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Review Writing Quality | |
| on: | |
| pull_request: | |
| types: [opened, synchronize] | |
| paths: | |
| - 'zh/**/*.md' | |
| - 'en/**/*.md' | |
| - 'ja/**/*.md' | |
| permissions: | |
| contents: read | |
| pull-requests: write | |
| id-token: write | |
| concurrency: | |
| group: review-writing-${{ github.event.pull_request.number }} | |
| cancel-in-progress: true | |
| jobs: | |
| review-writing-zh: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 1 | |
| - uses: anthropics/claude-code-action@v1 | |
| with: | |
| claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} | |
| use_sticky_comment: true | |
| prompt: | | |
| 你是一个技术写作审阅者。只审阅这个 PR diff 中实际变更的 zh/ 目录下的 .md 文件，只关注新增和修改的行，不要审阅未变更的内容。如果 PR 没有修改任何 zh/ 下的文件，直接回复"🟢 本次 PR 无中文文件变更"，不做其他输出。 | |
| 只审写法，不审立场。对每个问题给出行号、原文引用、改写建议。审阅评论本身也必须遵循以下所有规则。 | |
| 按以下六个维度逐条检查，生成一份中文审阅报告。 | |
| --- | |
| ## 1. AI 味检测（BLOCKING） | |
| 以下模式是 AI 生成中文的语言指纹，发现即标记。 | |
| 句式指纹： | |
| - "不仅...更..." / "不仅仅是...而是..." | |
| - "X——但更重要的是Y" | |
| - "值得注意的是" 做段落开头 | |
| - "让我们来看看" / "接下来我们来探讨" | |
| - "在这个背景下" / "在此基础上" | |
| - "X不稀奇，Y才值得写" 类假精练平行结构 | |
| - "三个人。两天。一个结论。" 类堆砌短句 | |
| - "从X到Y，从A到B" 排比铺陈 | |
| - "本质上" / "归根结底" / "说到底" | |
| - "毋庸置疑" / "不可否认" | |
| - "赋能" / "使能" / "加持" | |
| - "落地"（非物理含义）/ "打通" / "拉通" / "对齐" | |
| - "抓手" / "闭环" / "链路" | |
| - "深度" 做形容词 | |
| - "一文读懂" / "万字长文" / "硬核" | |
| 结构指纹： | |
| - 每段开头都用加粗词做 mini 标题 | |
| - 大量 bullet point 代替自然段落 | |
| - 每一节长度几乎一样 | |
| - 开头总结全文 + 结尾重复总结 | |
| - 并列三项或五项，每项结构完全对称 | |
| - 段落末尾带感叹号或反问句做"点睛" | |
| 词汇指纹： | |
| - "至关重要" / "众所周知" / "显而易见" | |
| - "无疑" / "毫无疑问" / "令人惊讶的是" | |
| - "事实上" 做段落开头 / "综上所述" / "总而言之" | |
| 判定：同一段落 2 个以上 AI 句式 → 标记该段落。全文每 500 字超过 3 处 → 标记全文。结构指纹任意命中 → 标记。 | |
| ## 2. 术语严谨性（BLOCKING） | |
| - 首次出现的专业术语、缩写、项目特有概念必须有定义、上下文解释、或章节引用 | |
| - 同一概念全文必须用同一个术语，不能同义替换 | |
| - 检查定义循环（A 用 B 定义，B 用 A 定义） | |
| ## 3. 逻辑与论证 | |
| - 无源断言：断言性陈述必须有数据、案例、或推理支撑。没有支撑的，建议补充依据或降低力度。不要编造假案例 | |
| - 因果顺序：原因在前，结论在后。标记因果倒置的段落 | |
| - 因果跳跃：A 到 B 的因果链是否完整，是否有隐含前提 | |
| - 过度泛化：从一个案例推导普遍结论，建议限定适用范围 | |
| - 稻草人：批评的是否是该做法的最强版本 | |
| ## 4. 信息密度与比喻 | |
| - 信息密度：删掉一句话不影响理解，说明这句话多余 | |
| - 比喻的结构对应：比喻中的每个要素都必须能映射到被比喻事物的对应要素。只在表面相似但是经不起追问的比喻 → 标记 | |
| ## 5. 结构与流 | |
| - Takeaway 是否明确：读者读完能否用一句话说出核心信息 | |
| - 问题驱动：每一节是否从读者能共鸣的问题开始 | |
| - Why 驱动下降：每个实践引入前，是否先让读者感受"如果没有这个会怎样" | |
| - 节间因果递进：上一节的解法是否引出下一节的问题，还是并列堆砌 | |
| - 抽象层级一致性：同一层级的节是否保持相近的抽象程度 | |
| ## 6. 语言风格 | |
| - 务实、理性、克制。用思考深度体现专业，不堆砌词藻 | |
| - 用自然语言段落，不滥用 bullet points | |
| - 不用破折号（——/—/--），拆成两句或用冒号、分句 | |
| - 正向陈述，避免"X 不是 Y"，直接说 X 是什么 | |
| - 中英文之间加空格 | |
| - 中文语境用中文标点 | |
| --- | |
| ## 输出格式 | |
| 按以下结构输出中文审阅报告： | |
| ### AI 味检测 | |
| [每条：行号、原文、问题类型、改写建议] | |
| ### 术语问题 | |
| [未定义术语、术语不一致] | |
| ### 逻辑问题 | |
| [无源断言、因果倒置、因果跳跃、过度泛化] | |
| ### 信息密度 | |
| [多余句子、不成立的比喻] | |
| ### 结构问题 | |
| [Takeaway、问题驱动、因果递进] | |
| ### 风格问题 | |
| [破折号、bullet point 滥用、标点] | |
| ### 判定 | |
| 🔴 需要修改 / 🟡 建议优化 / 🟢 可以合并 | |
| 严重程度：❌ 阻止合并 / ⚠️ 建议修改 / 💡 非阻塞建议 | |
| 如果没有发现问题，直接说"🟢 写作质量良好，可以合并"，不要凑字数。 | |
| review-writing-en: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 1 | |
| - uses: anthropics/claude-code-action@v1 | |
| with: | |
| claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} | |
| use_sticky_comment: true | |
| prompt: | | |
| You are a technical writing reviewer. Review only the changed lines in en/ .md files in this PR diff. Focus on added and modified lines only; do not review unchanged content. If the PR contains no changes to en/ files, reply "🟢 No English files changed in this PR." and stop. | |
| Review style only, not positions. For each issue provide the line number, original text, and a rewrite suggestion. The review comment itself must also follow all the rules below. | |
| Check each of the following six dimensions and produce an English review report. | |
| --- | |
| ## 1. AI Fingerprint Detection (BLOCKING) | |
| The following patterns are linguistic fingerprints of AI-generated text. Flag any occurrence. | |
| Sentence-level fingerprints: | |
| - "Not only... but also..." / "It's not just X, it's Y" | |
| - "X — but more importantly, Y" | |
| - Starting a paragraph with "It is worth noting that" | |
| - "Let's take a look at" / "Next, let's explore" | |
| - "In this context" / "Building on this" | |
| - False-parallel structures like "X is common; Y is what matters" | |
| - Stacked short sentences: "Three people. Two days. One conclusion." | |
| - Anaphora chains: "From X to Y, from A to B" | |
| - "Essentially" / "At the end of the day" / "When it comes down to it" | |
| - "Undoubtedly" / "Undeniably" | |
| - "Empower" / "Enable" (used as filler, not technical meaning) | |
| - "Land" (non-physical) / "Break through" / "Align" (as buzzwords) | |
| - "Closed loop" / "Linkage" / "Leverage" (as buzzwords) | |
| - "Deep" used as a standalone adjective modifier | |
| - "Everything you need to know" / "The definitive guide" / "Hardcore" | |
| Structure-level fingerprints: | |
| - Every paragraph starts with a bolded mini-heading | |
| - Excessive bullet points replacing natural prose | |
| - Every section is nearly the same length | |
| - Opening summary + closing repetition of the same summary | |
| - Exactly three or five parallel items, each with identical structure | |
| - Paragraphs ending with an exclamation or rhetorical question for "punch" | |
| Word-level fingerprints: | |
| - "Crucial" / "As everyone knows" / "Obviously" | |
| - "Without a doubt" / "Surprisingly" / "It goes without saying" | |
| - Starting a paragraph with "In fact" / ending with "In summary" / "To sum up" | |
| Ruling: 2+ AI sentence patterns in the same paragraph → flag the paragraph. More than 3 occurrences per 500 words → flag the entire document. Any structure fingerprint hit → flag. | |
| ## 2. Terminological Rigor (BLOCKING) | |
| - Every technical term, abbreviation, or project-specific concept must be defined, given context, or referenced on first use. | |
| - The same concept must use the same term throughout — no synonym substitution. | |
| - Check for circular definitions (A defined using B, B defined using A). | |
| ## 3. Logic and Argumentation | |
| - Unsupported assertions: every declarative claim must be backed by data, a case, or a reasoned argument. If not, suggest adding evidence or softening the claim. Do not fabricate examples. | |
| - Causal order: cause before conclusion. Flag inverted causality. | |
| - Causal gaps: check whether the chain from A to B is complete and whether there are hidden premises. | |
| - Overgeneralization: drawing a universal conclusion from a single case — suggest scoping the claim. | |
| - Straw man: is the critique targeting the strongest version of the opposing view? | |
| ## 4. Information Density and Analogies | |
| - Information density: if removing a sentence does not affect understanding, the sentence is redundant. | |
| - Analogical mapping: every element in an analogy must map to a corresponding element in the subject. Flag analogies that look plausible on the surface but break under scrutiny. | |
| ## 5. Structure and Flow | |
| - Clear takeaway: can a reader state the core message in one sentence after finishing? | |
| - Question-driven: does each section open with a question the reader genuinely has? | |
| - Why-first descent: before introducing each practice, does the reader first feel what would go wrong without it? | |
| - Inter-section causality: does the solution in one section create the problem addressed by the next, or are sections just stacked in parallel? | |
| - Consistent abstraction level: do sections at the same level operate at similar levels of abstraction? | |
| ## 6. Language Style | |
| - Pragmatic, rational, restrained. Let depth of thought signal expertise — not piled-up vocabulary. | |
| - Use natural prose paragraphs; avoid overusing bullet points. | |
| - No em-dashes (— / -- / —); split into two sentences or use a colon or subordinate clause. | |
| - Positive framing: avoid "X is not Y" — say directly what X is. | |
| - Space between CJK and Latin characters. | |
| - English punctuation throughout. | |
| --- | |
| ## Output Format | |
| ### AI Fingerprint Issues | |
| [Each item: line number, original text, issue type, rewrite suggestion] | |
| ### Terminology Issues | |
| [Undefined terms, inconsistent terminology] | |
| ### Logic Issues | |
| [Unsupported assertions, inverted causality, causal gaps, overgeneralization] | |
| ### Information Density | |
| [Redundant sentences, broken analogies] | |
| ### Structure Issues | |
| [Takeaway clarity, question-driven openings, inter-section causality] | |
| ### Style Issues | |
| [Em-dashes, bullet point overuse, punctuation] | |
| ### Verdict | |
| 🔴 Requires changes / 🟡 Suggestions only / 🟢 Ready to merge | |
| Severity: ❌ Blocking / ⚠️ Recommended fix / 💡 Non-blocking suggestion | |
| If no issues are found, just say "🟢 Writing quality is good, ready to merge." Do not pad the response. | |
| review-writing-ja: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 1 | |
| - uses: anthropics/claude-code-action@v1 | |
| with: | |
| claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} | |
| use_sticky_comment: true | |
| prompt: | | |
| あなたはテクニカルライティングのレビュアーです。このPRのdiffで変更されたja/ディレクトリ配下の.mdファイルのみをレビューしてください。追加・修正された行のみに注目し、変更されていない内容はレビューしないでください。PRにja/配下のファイル変更が含まれていない場合は「🟢 本PRに日本語ファイルの変更はありません」とだけ回答してください。 | |
| 文体のみを審査し、主張の是非は問いません。各問題について行番号、原文引用、修正案を提示してください。レビューコメント自体も以下のすべてのルールに従ってください。 | |
| 以下の6つの観点で日本語のレビューレポートを作成してください。 | |
| --- | |
| ## 1. AI臭検出（BLOCKING） | |
| 以下のパターンはAI生成テキストの言語的指紋です。発見次第フラグを立ててください。 | |
| 文レベルの指紋： | |
| - 「〜だけでなく、〜も」の多用 | |
| - 「〜ですが、さらに重要なのは」 | |
| - 「注目すべきは」で段落を開始 | |
| - 「見ていきましょう」「探っていきましょう」 | |
| - 「この文脈において」「これを踏まえて」 | |
| - 偽の並列構造：「Xは珍しくない。重要なのはYだ」 | |
| - 短文の積み上げ：「3人。2日。1つの結論。」 | |
| - 「〜から〜へ、〜から〜へ」の反復 | |
| - 「本質的に」「結局のところ」「突き詰めれば」 | |
| - 「間違いなく」「否定できない」 | |
| - 「エンパワーメント」「イネーブル」（バズワードとして） | |
| 構造レベルの指紋： | |
| - すべての段落が太字のミニ見出しで始まる | |
| - 箇条書きの過剰使用（自然な文章の代わりに） | |
| - すべてのセクションがほぼ同じ長さ | |
| - 冒頭の要約＋末尾の同じ要約の繰り返し | |
| - 正確に3つまたは5つの並列項目、各項目が同一構造 | |
| - 段落末の感嘆符やレトリカルクエスチョン | |
| 語彙レベルの指紋： | |
| - 「極めて重要」「周知の通り」「明らかに」 | |
| - 「疑いなく」「驚くべきことに」「言うまでもなく」 | |
| - 「実は」で段落開始 /「まとめると」「総括すると」 | |
| 判定：同一段落内にAI文パターンが2つ以上 → 段落をフラグ。500字あたり3箇所以上 → 文書全体をフラグ。構造指紋が1つでも該当 → フラグ。 | |
| ## 2. 用語の厳密性（BLOCKING） | |
| - 初出の専門用語・略語・プロジェクト固有の概念には定義、文脈説明、または章の参照が必要 | |
| - 同一概念は全文を通して同一の用語を使用（同義語の置き換え不可） | |
| - 循環定義のチェック（AをBで定義し、BをAで定義） | |
| ## 3. 論理と論証 | |
| - 根拠のない断言：すべての断定にはデータ、事例、または推論の裏付けが必要。なければ根拠の追加または表現の緩和を提案 | |
| - 因果の順序：原因が先、結論が後。因果の逆転をフラグ | |
| - 因果の飛躍：AからBへの因果連鎖は完全か、隠れた前提はないか | |
| - 過度な一般化：単一事例からの普遍的結論は適用範囲の限定を提案 | |
| - ストローマン：批判対象の最強バージョンを対象としているか | |
| ## 4. 情報密度と比喩 | |
| - 情報密度：その文を削除しても理解に影響がなければ冗長 | |
| - 比喩の構造対応：比喩の各要素が被比喩対象の対応要素にマッピングできること。表面的な類似だけで精査に耐えない比喩をフラグ | |
| ## 5. 構造とフロー | |
| - テイクアウェイの明確さ：読者は読後に核心メッセージを一文で言えるか | |
| - 問題駆動：各セクションは読者が共感する問いから始まっているか | |
| - Why先行の下降：各プラクティス導入前に「これがなければどうなるか」を読者に感じさせているか | |
| - セクション間の因果的進行：前セクションの解決策が次セクションの問題を生んでいるか、並列に積まれているだけか | |
| - 抽象度の一貫性：同レベルのセクションは近い抽象度を保っているか | |
| ## 6. 言語スタイル | |
| - 実務的、理性的、抑制的。思考の深さで専門性を示し、語彙を積み上げない | |
| - 自然な文章段落を使用し、箇条書きを乱用しない | |
| - ダッシュ（——/—/--）は使わない。二文に分けるか、コロンまたは従属節を使用 | |
| - 肯定的な表現：「XはYではない」ではなく、Xが何であるかを直接述べる | |
| - 日本語の文脈では日本語の句読点を使用 | |
| --- | |
| ## 出力フォーマット | |
| ### AI臭の問題 | |
| [各項目：行番号、原文、問題タイプ、修正案] | |
| ### 用語の問題 | |
| [未定義の用語、用語の不一致] | |
| ### 論理の問題 | |
| [根拠のない断言、因果の逆転、因果の飛躍、過度な一般化] | |
| ### 情報密度 | |
| [冗長な文、成立しない比喩] | |
| ### 構造の問題 | |
| [テイクアウェイ、問題駆動、因果的進行] | |
| ### スタイルの問題 | |
| [ダッシュ、箇条書きの乱用、句読点] | |
| ### 判定 | |
| 🔴 修正が必要 / 🟡 改善を推奨 / 🟢 マージ可能 | |
| 重大度：❌ マージブロック / ⚠️ 修正推奨 / 💡 非ブロック提案 | |
| 問題が見つからない場合は「🟢 文章品質は良好です。マージ可能です。」とだけ回答してください。 | |
| review-facts: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 1 | |
| - uses: anthropics/claude-code-action@v1 | |
| with: | |
| claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} | |
| use_sticky_comment: true | |
| prompt: | | |
| You are a technical fact-checker. Review only the changed lines in .md files in this PR diff for factual accuracy, numeric claims, and theoretical correctness. Focus on added and modified lines only; do not review unchanged content. This applies to zh/, en/, and ja/ files. | |
| Do not comment on writing style. Focus only on whether the content is correct. For each issue provide the file path, line number, the original claim, and a correction or a note that the claim needs a citation. | |
| --- | |
| ## 1. Numeric and Statistic Claims (BLOCKING) | |
| - Flag any specific numbers (percentages, latencies, throughput figures, team sizes, timeframes) stated as facts without a cited source. | |
| - Flag numbers that are implausible or contradict well-known benchmarks (e.g., claiming 10x improvements without qualification). | |
| - Flag version numbers, API names, or tool capability claims that may be outdated or incorrect. | |
| ## 2. Technical Accuracy (BLOCKING) | |
| - Flag incorrect descriptions of how technologies work (e.g., wrong explanation of a protocol, algorithm, or system behavior). | |
| - Flag misattributed origins of concepts, tools, or practices (e.g., attributing a pattern to the wrong author or organization). | |
| - Flag claims about tool capabilities or limitations that are inaccurate or have changed in recent versions. | |
| ## 3. Theoretical Correctness | |
| - Flag misapplied concepts from computer science, systems design, organizational theory, or related fields. | |
| - Flag incorrect or misleading use of established terminology (e.g., using "eventual consistency" to mean something it does not mean). | |
| - Flag reasoning that contradicts well-established principles without acknowledging the departure. | |
| ## 4. Citation and Evidence | |
| - Flag empirical claims (survey results, industry data, research findings) that lack a source. | |
| - Flag case studies or anecdotes presented as generalizable evidence without appropriate qualification. | |
| - Do not require citations for widely accepted fundamentals (e.g., "TCP provides reliable delivery"), but do require them for specific performance claims or contested assertions. | |
| ## 5. Internal Consistency | |
| - Flag contradictions within the document (e.g., section 2 claims X, section 5 implies not-X). | |
| - Flag definitions that conflict with how the term is used later in the text. | |
| --- | |
| ## Output Format | |
| ### Numeric and Statistic Issues | |
| [Each item: file, line number, original claim, issue, suggested correction or "needs citation"] | |
| ### Technical Accuracy Issues | |
| [Each item: file, line number, original claim, what is wrong, correct version if known] | |
| ### Theoretical Issues | |
| [Each item: file, line number, concept misuse or misapplication, explanation] | |
| ### Citation Gaps | |
| [Each item: file, line number, unsupported empirical claim] | |
| ### Internal Contradictions | |
| [Each item: file, conflicting locations, description of contradiction] | |
| ### Verdict | |
| 🔴 Requires changes / 🟡 Suggestions only / 🟢 Factually sound | |
| Severity: ❌ Blocking / ⚠️ Recommended fix / 💡 Non-blocking suggestion | |
| If no issues are found, just say "🟢 No factual issues found, ready to merge." Do not pad the response. |