gracker-writing

技術記事の執筆

技術者向けの執筆スキルです。特に Android、パフォーマンス最適化、エンジニアリングツール、システムの仕組みに関する内容に適しています。 執筆の方向性：エンジニアの視点で、技術的に正確で、構成が明快、判断が明確、実践の痕跡が濃く、知識をひけらかさず、気取らない文章です。 長文は本ファイルに従ってください。X/Twitter、ソーシャル向けまとめ、定期投稿用の原稿は、まず各プラットフォームのスキルに沿って構成し、その後 references/social-output-gate.md でチェックしてください。

技術記事の要点は3つです。

1. 正確さ：用語、バージョン、パス、コード、データがすべて一致していること。
2. 有用さ：読者が読み終えた後、どう観察し、どう判断し、どう手を動かせばよいかが分かること。
3. 読みやすさ：情報を詰め込むのではなく、複雑な問題を順序立てて説明すること。

ニュースの転載でも、感情のぶつけ合いでも、AI 風の整っただけの空疎な文章でもありません。「見栄え」をよくするための小細工もしません。

人間味の基準

執筆、リライト、公開前の品質チェックでは、references/human-feel.md を読み込んでください。このルールは human-writing の要点を取り入れつつ、Gracker の技術記事執筆体系に合わせて表現し直したものです。具体的な事実を優先し、簡潔な動詞を使い、話を大きくしすぎず、三項目に無理にまとめず、用語を安定して使い、見解の出どころを明確にし、強調は控えめにし、飾り立てないことを重視します。

人間味は口語的な演出から生まれるのではなく、次の3つから生まれます。

• 具体性：場面、ツール、バージョン、trace、コードパス、失敗する分岐、読者からの反応が見えること。
• 取捨選択：著者がなぜそう判断したのか、その判断がどのような条件で成り立つのかが分かること。
• 気取らなさ：ありふれた事実を時代の潮流のように書かず、資料をまとめただけのことを深い洞察のように見せず、書式上の重点を内容上の重点と取り違えないこと。

気取った表現：気取った表現はすべて削除してください。直接説明できるときは、比喩や美辞麗句、書き手らしさの演出で正確な意味を置き換えず、直接説明してください。 気取った文章はすべて取り除いてください。字義どおりに説明できるなら、比喩や華美な表現、意味を伝えるのではなく書き手を演出する言葉ではなく、その説明を使ってください。

具体的な対象、動作、証拠のいずれもない段落は、たとえ滑らかに読めても、著者として不合格と判断してください。不足しているのは材料であり、「人間らしさ」ではありません。

AI らしさをなくす作業は2つの層に分け、混同しないでください。コーパス層では references/less-ai-tone.md を読み、精修では該当するトリガーがある11項目だけを変更し、情報を増減させないでください。著者層ではこの節と human-feel.md を引き続き参照してください。精修の際、「人間が書いたように」見せることを理由に、口語表現を加えたり、文の長さを調整したり、疑問文や比喩を削除したり、受動態を翻訳調と見なしたりしてはいけません。そうした項目はコーパスとして根拠がありません。

ソーシャル向け原稿とニュース向け原稿には、音読テストを追加してください。書き終えたら、すべての文を声に出して読んでください。資料の前書きを書いているように聞こえる文、公式サイトのレイアウトを論評しているように聞こえる文、評価機関が記事をどう構成しているかを分析しているように聞こえる文など、普通なら同僚にそう話さない文は、文全体を書き直してください。主語には製品、モデル、数字を使い、「公式サイトが画面／売り文句／ストーリーを……」とは書かないでください。比較文には必ず具体的な数字を2つ入れ、「伸びが大きい」「上昇幅が大きい」のような中身のない比較は禁止です。詳しくは references/human-feel.md の「思考の流れ」を参照してください。

ソーシャル向け出力のチェック

X/Twitter、thread、小紅書、ソーシャル向けまとめ、定期投稿として Telegram に投稿する原稿は、用語チェックだけでは不十分です。納品前に必ず references/social-output-gate.md を読み込んでください。

この種の原稿で最もよくある失敗は、禁止語の使用ではなく、changelog を「きれいな長文投稿」にまとめてしまうことです。否定的な書き出し、機能の1、2、3という列挙、内容を大きく見せる包装、スローガンのような締めくくりが該当します。同ファイルの「失敗したら書き直す」にある項目に2つ以上当てはまる場合は、表面的な置き換えで済ませず、記事全体を書き直してください。

DeepResearch、調査結果、レビューのまとめをソーシャル向けの長文（知乎／WeChat公式アカウント／シェア可能な長文投稿）として発信する場合は、まず references/research-social-longform.md を読んでください。「意外性 → 数字の比較 → 画像 → 本当の問い」という流れで展開し、調査レポートの章タイトルを小見出しとして使わないでください。構成だけを参考にし、サンプルの口癖はまねしないでください。

プラットフォームの構成は対応するスキル（例：x-tweet-writer）に従ってください。文体、AI らしさ、話を大きく見せる表現、締めくくりはこのスキルに従ってください。ソーシャル向け本文に内部プロセス、パス、スキル名、品質チェックレポートを含めないでください。定期投稿として Telegram に投稿する原稿は、ユーザーが全文を選択し、ソーシャルプラットフォームにそのまま貼り付けられる完全な本文でなければなりません。情報、判断、リンクは文章の中に含めてください。「台帳」のような内輪の言葉、status、スコア、保存先のパス、「今日のおすすめ」、Obsidian の作業原稿全体の投稿は避けてください。長くなることは問題ありません。問題なのは、内容が乱雑になることです。材料があれば詳しく書き、各段落に中心となる内容を1つだけ置き、順序立ててください。整然と見せるためにアウトラインに圧縮したり、箇条書きを散らばらせたりしないでください。

---

一、執筆の原則

中心目標

読者が本当に理解し、実際に活用し、適用範囲を把握できるようにすること——著者が詳しいと思わせることではありません。

6つの基本原則

1. 感情の視点より、エンジニアの視点を優先する：まず問題、システム、ツール、手順を説明し、その後で感想や態度を述べます。
2. 著者自身が実際に関わっていること：記事から実際のワークフローの痕跡が見えるようにします。なぜその問題に遭遇したか、どう観察したか、どのツール／trace／コマンド／コードパスを使ったか、どの手順で誤判断しやすいか、自分がどう判断したかを示します。
3. 構成を明確にし、見出しだけで内容が分かるようにする：読者は見出しをざっと見るだけで、記事全体の骨格が分かるようにします。
4. 判断を明確にし、根拠と適用範囲を必ず示す：判断を述べた後は、必ず根拠、条件、適用範囲を示します。
5. 技術的な内容を具体的に書く：ツール名、モジュール名、クラス名、トラック名、パラメーター、バージョン、パス、コマンドを具体的に記載します。
6. 結びは控えめにし、空疎なまとめで話を大きくしない：技術記事は要点をまとめて締めくくり、無理に高尚な結論へ持ち上げないでください。

情報密度

目指すのは「すべての文をぎっしり詰めること」ではなく、「すべての文が理解を前進させること」です。

• 1つの段落では1つの役割だけを果たします。定義、仕組みの説明、証拠の提示、判断を混ぜないでください。
• 情報密度の高い説明段落の途中には、短い結論文／リスト／図表／コードの確認箇所を挟み、読者が一息つけるようにします。
• 新しい概念を4つ以上続けて詰め込まないでください。必要であれば段落を分けます。
• 中心的な見解は記事全体で2回だけ登場させます：定義とまとめです。中盤ではそのまま使い、繰り返し説明しないでください。
• 削除しても理解に影響しない段落は「正しいだけの無駄話」です。削除してください。

読みやすい間

読みやすい間とは抒情ではなく、認知負荷を抑えることです。

• 長い説明段落の後には、短い判断文を置きます。
• 複雑な仕組みを説明する前に、全体像を示します。
• 長いコードブロックの前に、「どの行に注目するか」を説明します。
• 要所では、読者を導く言葉を加えます。例：まず1つ結論を覚えておいてください：...／ここまでで、A と B の違いが明確になりました。

表面的な網羅性より読みやすさを優先する

展開の順序：問題は何か → なぜ注目する価値があるか → まず全体像をつかむ → 次に細部を掘り下げる → 最後に判断と適用範囲を示す。すべてを一度に説明する必要はありません。読者の理解の順序に沿って説明してください。

---

二、記事の構成

よくある長文の5つの種類

1. 技術の深掘り／シリーズ解説：仕組み、観測方法、分析手順を明らかにします。構成：問題の定義 → 背景となる概念 → システムの流れ → trace／コード／図解 → 実践的な提案。
2. ツールの実践／アーキテクチャの振り返り：なぜそのように設計したか、どう実装したか、どんな問題に直面したかを説明します。構成：きっかけ → 重要な判断 → ソリューションの分解 → トレードオフ → 適用範囲。
3. FAQ/Q&A：読者が最も気にしている質問を1つずつ掘り下げます。構成：質問の一覧 → 質問ごとの結論 → 証拠／誤解／適用範囲。
4. 方法論／業界の動向／判断型記事：分散した経験を判断の枠組みにまとめます。構成：現実の問題 → 著者の判断 → 観点ごとの分析 → 反例／代償／適用範囲。
5. ツール体験／読書／コミュニティ／人物紹介：個性を出しつつ、実用的な価値を提供します。構成：きっかけ → 内容／ツール／見解 → 著者による補足と理解 → 推薦／まとめ。

デフォルトの骨格

【开头】直接交代问题、场景、文章任务
  ↓
【背景】为什么值得聊,读者能带走什么,需要哪些前置知识
  ↓
【主体】按 3 到 8 个板块展开,每块只解决一个问题
  ↓
【判断】把局部观察提炼成更高一层的理解
  ↓
【结尾】压缩结论、补边界、给后续阅读或行动建议

書き出し

3文以内に、次の3つを必ず示します。この記事で何を扱うのか、なぜ読む価値があるのか、読み終えた後に何を持ち帰れるのか。

よく使う4種類の書き出し：

• シリーズの位置づけ型：この記事は XXX シリーズの第 N 回で、主に YYY を取り上げます。
• 最近の出来事／読者の反応型：前回の記事を公開した後、最も多く寄せられた質問は...でした。
• 認識の修正型：以前どう考えていたかを述べ、実際に使ってみて何が分かったかを説明します。
• 先に判断を示す型：最初に判断を示し、その後で理由と適用範囲を掘り下げます。

書き出しで避けること：

• 「この時代では」「技術の発展に伴い」から始めないでください。
• 大きな背景を先に語り、徐々にテーマに近づけないでください。
• ありきたりな正論を前置きにしないでください。
• 目次のような構成を報告書のように見せないでください。

本文

• 1段落1つの意味：各段落の役割は1つだけにし、1つの段落で3つのことを同時に扱わないでください。
• 全体像を示してから掘り下げる：全体像 → 主要なモジュール → trace／コード／データ → 結論。
• 要所で読者を導く：まず全体像を把握します。／ここでは、まず1つの違いを覚えておいてください。／次に、この結論に至った理由を見ていきます。
• 順序を設計する：まず基準を示し、次に応用例を挙げ、最後に理解を最も変える例を示します。
• 概要と詳細の役割を分ける：「概要」と「詳細」の2つの章がある場合、概要では結論だけを示し（2～4行）、詳細で内容を掘り下げます。同じ内容を両方で繰り返さないでください。
• シリーズ記事では繰り返さない：前の記事ですでに定義した概念は参照するだけにし、再度説明しないでください。
• 他者をまねるときは、文型ではなく構成をまねる：参考にするのは判断のまとめ方や証拠を並べる順序であり、表面的な文型や過去の書式上のノイズではありません。
• プロジェクト固有のルールを共通ルールに混ぜない：プロジェクト固有の用語、バージョン表記、ブランドの語調、情報設計はプロジェクト固有の上書きルールに記載し、共通の執筆規則には含めないでください。

文型とリズム

1. 先に要点を述べ、その後で掘り下げる：最初の1、2文で中心を伝え、回りくどい説明をしないでください。
2. 長文には情報を盛り込み、短文で結論を打ち出す：長文で背景／適用範囲／対象を説明し、短文で判断を示します。
3. 一人称を使わない：「私はこう思います」「私はこう提案します」「通常はこうします」と書かず、結論や手順を直接示します。
4. 実際の細部は使っても、演出はまねしない：迷い、取捨選択、失敗した経験は含めてもかまいません。強い感情の噴出、ネット上の口癖、芝居がかった冗談のような表現は避けてください。

締めくくり

優先する締め方は次の4つです。

1. 判断を一文で示して締めます。
2. 本文の後に参考資料や関連資料を示します。
3. 読者が次に取る行動を示します。
4. 冒頭の問いに一度だけ立ち返ります。文学的な円環表現にはしません。

締めくくりで避けること:

• 突然、話を大きな価値観に結びつけないでください。
• 結論をスローガンにしないでください。
• 何も述べていないのに、開かれた結末を装わないでください。
• 全文の内容を曖昧に繰り返さないでください。

---

三、使用禁止の語句と文型

詳しいルールは references/style-rules.md、references/less-ai-tone.md、references/copy-editing.md、references/document-style-guide.md、references/chinese-copywriting-guidelines.md、references/human-feel.md を参照してください。執筆、リライト、品質チェックの前に、必要に応じて必ず読み込んでください。

文章の推敲やAIらしさを取り除く際は、まず references/less-ai-tone.md を読んでください。論点のすり替え、読点の過剰な使用、隣り合う文の同型表現、種明かしのようなダッシュ、案内文や中身のない文に続くコロン、序数を使った小見出し、擬人化した比喩、データを上回る一般化、5種類の翻訳調、主語のない段落冒頭を確認します。次に、執筆者の観点から、使用禁止語、意味の過剰な膨張、想定読者の誤り、冗長な確認の副詞、技術文書で宙に浮いた動詞、構成についてのメタ的な説明、類義語の使い分け、気取り、会話を誘導する表現に対処します。中国語の技術文書の文型は阮一峰の採用稿に従い、中国語と英語の組版は「排版指北」の採用稿に従います。

Android、パフォーマンス最適化、Perfetto、システムの仕組みに関する記事では、references/android-terminology.md も読み込んでください。これらの記事では、渲染链路、输入链路、Binder 调用链、BufferQueue、fence などが正確な用語である場合があります。用語集に含まれているからといって、機械的に置き換えてはいけません。

---

四、表示規則

コード

1. コードブロックの前に必ず「用途を示す文」を置く：このコードで何を示すのか、読者はどこに注目すべきか、読み終えたときにどのような結論が得られるかを説明します。
2. コードブロック内を読みやすくする：標準的な Markdown コードブロックを使い、言語を指定します。命名、インデント、改行は言語のスタイルガイドに従います。
3. 省略する場合は明示する：対象言語のコメントで示し、曖昧な ... は使いません。例：// Several unrelated lines are omitted.
4. コードの後に必ず「説明文」を置く：ここが重要な理由、前述の結論との対応、実際の利用時にどのように確認するかを説明します。
5. 長いコードの扱い：本文には骨格と主要な処理経路だけを残し、長すぎるコードはリポジトリ、Gist、付録に置きます。
6. コードの品質：実行可能なものは実行可能な形で示します。実行できないものは「例示／擬似コード／抜粋」と明記します。存在しない API、クラス名、メソッド名を作ってはいけません。

データ

1. まず表現形式を決める：一文で説明できるなら文章、比較項目が少なければリスト、複数の指標を比較するなら表、傾向や変動ならグラフ、時系列の関係ならフローチャートを使います。
2. データには必ず比較対象を示す：数値には必ず単位、測定条件、比較基準、安定して再現するかどうか、サンプル範囲を補います。
3. 表を情報の寄せ集めにしない：読者が横並びで比較する必要のある項目だけを載せます。
4. グラフを飾りにしない：明確な問いに答えるものにします。
5. 結論をデータに結びつける：グラフや表の後には、このデータが何を裏付け、何を裏付けないのかを説明する一文を必ず加えます。

リスト

**基本原則：リストを目次にせず、内容を示します。**各項目には新しい情報を含め、その項目を読んだだけで「これは何か／なぜ必要か／どう使うか」が分かるようにします。

❌ 禁止される書き方：

- threads
- slices
- counters

✅ 適切な書き方：

- threads:按 tid 分组的线程轨道,用于定位主线程、RenderThread、Binder 线程的执行时间
- slices:函数调用的时间区间,颜色深度表示调用栈层级,用于定位哪个函数耗时长

判断基準：項目の説明を削って名詞だけを残したとき、読者が知る情報は減りますか。減らないなら、説明が足りません。

図表

図表の種類	ツール	コードフェンス	適した用途
フローチャート／シーケンス図／状態機械	mermaid	```mermaid	レンダリングパイプライン、VSync のタイミング、状態遷移
レイヤー構成図	architecture	```architecture	システムアーキテクチャ、モジュールの階層
データグラフ（棒／折れ線／散布図／ヒートマップ）	vega	```vega-lite	フレームレートの推移、消費電力の比較、温度の推移
複雑な依存関係／呼び出し図	graphviz	```dot	クラス継承、Binder の呼び出しチェーン、モジュールの依存関係ツリー
インフォグラフィック／タイムライン／比較	infographic	```infographic	最適化効果の比較、ツールの評価、方法論の全体像
マインドマップ／ナレッジグラフ	canvas	```canvas	ナレッジ体系の構造、概念の関係

選択の原則：mermaid で表現できるなら graphviz は使いません。データの比較には vega を優先し、レイヤー構成には architecture を優先します。WeChat 公式アカウントの記事では、mermaid と infographic を優先します（描画の互換性が高いため）。

アーキテクチャ図で省略できる範囲：シーケンス図やアーキテクチャ図では、装飾や同じ階層の細部は省略できます。ただし、読者が trace を追うために必要な中継レイヤーは省略できません。判断基準は、そのノードに Perfetto trace 上の独立したスレッド、counter、slice があるかどうかです。ある場合は省略できません。図を trace と照らし合わせたときに対応する要素が見つからなければ、「そこを直接飛び越えている」と誤解されます。図を描く前に、「読者がこの図を trace と照らし合わせるとき、どのキーワードを探すか」と考えてください。そのキーワードに対応するノードはすべて図に含める必要があります。

用語

• 安定した日本語訳がある英語は日本語に置き換えます（翻訳調のパターン4）。AI が生成した文章には、context、state、cache、claim などの英語がそのまま残りがちです。読者はそのたびに「context → 文脈」「claim を強める → 判断をより強く述べる」と頭の中で切り替える必要があります。一段落で何度も切り替えると、読むだけで疲れてしまいます。
  • 安定した訳語がある場合は、必ず翻訳します：文脈（context ではなく）、状態（state ではなく）、キャッシュ（cache ではなく）、主張（claim ではなく）、ランタイム、プロトコル層、契約層。
  • まだ訳語が定まっていない用語は英語のままにします：prompt、embedding、tokenizer、harness、agent などは、中国語の技術コミュニティで一般的な訳語がまだ定着していません。
  • 判断基準：中国語のコミュニティで、その概念に統一された用語があるかどうかです。ある場合は中国語に置き換え、ない場合は英語のままにします。英語を残すのは「中国語のコミュニティで公認された訳語がまだない」場合であり、「書き手が訳したくない」場合ではありません。
• 例外：固有名詞や識別子として定着した英語はそのままにします。Android、Perfetto、VSync、Binder、trace_processor、Workflow、Agent（RN／LangChain などのフレームワーク内の具体的なコンポーネント名として使う場合）などです。
• Android の記事では、まずシステムオブジェクトと観測証拠を基準に用語を判断します。ソースコードのクラス、システムサービス、スレッド、trace のトラック、slice／counter、buffer／fence の状態に対応する用語は専門用語として扱います。具体的な対象や境界がない場合は、スラングとして扱います。
• 本文中で目に見える用語だけを修正します。コード、フィールド、パス、URL、trace 名、スレッド名、counter 名、外部からの引用文は機械的に変更しません。
• 新しい概念が初めて登場するときは、まず平易な説明を一文で加えてから詳しく説明します。
• 「分かりやすさ」のために正確さを犠牲にしてはいけません。専門用語を、さらに曖昧な別の専門用語で説明しないでください。

---

五、AI との協業規則

AI が得意な作業

• 資料、アウトライン、目次の整理
• 既存の見解を、より完全な構成に広げる
• 分かりやすさを比較できるよう、複数の説明案を提示する
• 読みやすさのチェック項目を補い、専門用語、重複文、AI らしい文型を見つける
• 表、チェックリスト、比較マトリクスの整理を支援する
• 既定の観点に沿って、既存の段落を拡充する

AI が著者の代わりにできないこと

• 記事の中心となる切り口を決める
• 一次体験、実験、trace の観察結果、パフォーマンスデータを捏造する
• 技術的な正確性に対する責任を著者の代わりに負う
• 最終的な取捨選択や判断を著者の代わりに行う
• 著者の開発環境で実際に動かしたかのように装う

協業の流れ

人:给出主题、读者对象、自己的判断、真实经历、关键证据
  ↓
AI:整理结构、补参考资料、提出可读性优化方案
  ↓
人:补一手细节、删错的、改判断、压风格
  ↓
AI:按四层质检做检查,指出具体问题
  ↓
人:终审,确认准确性、边界、可发布性

必跑：写作后质检不是可选步骤

按本 skill 生成的第一版只能算草稿,不能直接当发布稿。尤其是公众号/知乎长文、技术方法论、外文观点解读这类任务,模型会自然滑回「不是 X,而是 Y」「不只是 X,还 Y」「真正/其实/实际上」等高频论述句式。即使结构和内容已经符合本 skill,也必须在交付前跑一轮规则扫描和硬修。

交付前至少检查并修掉:

• 不是[^。\n]{0,25}而是|不只是[^。\n]{0,25}还|并非[^。\n]{0,25}而是|不仅仅是[^。\n]{0,25}更是|与其说
• 真正|实际上|其实|根本|彻底|确实 高频副词,单词累计过多要压掉,无信息增量的全部删
• 最值得看|最值得|值得一看 等用户明确不喜欢的评价 opener
• 把画面|把卖点写成|把评测拆|叙事转到|官网把|跳得更|升幅大 机构拟人/空比较；命中就改成「谁、数字、跟谁比」
• 中文排版按 references/chinese-copywriting-guidelines.md 扫中英文/数字空格、单位空格、重复标点；按 references/document-style-guide.md 扫双重否定、「降低 N 倍」、标题跳级。不要把被动句本身当不合格
• 语料层按 references/less-ai-tone.md 扫翻案腔、空转句冒号、段首零主语、过长前置定语、「当……时」、前置话题壳、句首「然而/因此/此外」、「这意味着」复述。未命中的句子不要改
• 结构性元叙述、假想读者错误、意义通胀、顺手补分析。正文「首先……其次」和问句不要当 AI 味删
• 社交稿再按 references/social-output-gate.md 扫一遍：changelog 综述、否定开场、一、二、三 功能并列、口号收尾、名人硬挂钩、导演句、空比较
• 社交稿出声测试：每句问「朋友之间会不会这么说」；不会就重写，不要只换词

工作顺序固定为:先按 skill 出完整稿 → 立刻扫描 → 硬修句式和禁用词 → 抽读关键段落 → 再交付可发布版。不要把“按 skill 写了”误当成“通过 skill 质检”。

硬规则

• 不能把 AI 生成的"像真的"当成"真的"——必须核实。
• 不能让 AI 自动补齐不存在的实验结论。
• 不能把 AI 的平滑表述原样端上去——必须二次改写。
• 不能一轮生成直接发布。
• 不能抄别人的框架/观点不标来源。
• 发布稿只面向读者,不留编辑痕迹:正文中不出现"这一版"/"上一稿"/"按要求改过"等写作过程记录。

---

六、质检体系

完整四层质检规则见 references/quality-gate.md。写完后按 L1 硬性规则、L2 可读性、L3 内容深度、L4 活人感逐层检查；L4 必须纳入 references/human-feel.md 的具体性、意义通胀、同义词轮换、格式用力过猛和矫饰性表达检查，以及 references/less-ai-tone.md 的语料层 11 条。社交稿还要过 references/social-output-gate.md。质检只输出报告，不自动修改内容；社交稿质检不通过则重写正文，再交可发布版。精修任务按白名单改写，不要把质检报告里的「语感 AI 味」扩成改写范围。

---

七、精修 mode

当用户要求“精修”“润色但不重写”“只改 AI 味”时，先读 references/less-ai-tone.md，再读 references/refinement-mode.md 和 references/human-feel.md。精修只动词句和格式，不改结构、事实判断或新增论点。语料层白名单未命中的句子逐字保留。