diff --git a/dot_claude/CLAUDE.md b/dot_claude/CLAUDE.md index 8be3806..1679b39 100644 --- a/dot_claude/CLAUDE.md +++ b/dot_claude/CLAUDE.md @@ -24,6 +24,7 @@ - AI向けドキュメント(AGENTS.md など)は断定する。どちらとも取れる書き方を避ける - 日本語でダッシュ・横線記号(`—` `──` `―`)を使わない。ファイル編集でもチャット応答でも同じ。英語では可 - 日本語で箇条書きの直前に `:` を置かない +- Issue、PR、記事、ドキュメントなど出典のあるものに言及するときは、言及した文の中で Markdown リンクにする。裸の番号・裸の URL を書かない。同一リポジトリでも `#123` ではなく `[#123](https://github.com/org/repo/issues/123)` とフル URL で書く。文末のリンク一覧は本文中リンクの代わりにならない。対象は記事・Issue/PR 本文・ドキュメントで、チャット応答は対象外 ## 言語 diff --git a/dot_claude/references/issue_pr_rules.md b/dot_claude/references/issue_pr_rules.md index 29adfbe..5d39319 100644 --- a/dot_claude/references/issue_pr_rules.md +++ b/dot_claude/references/issue_pr_rules.md @@ -8,6 +8,15 @@ Always use GitHub permalinks (commit SHA-based) when referencing source code in - Always use commit SHA-based links (`/blob/abc1234/...`) - Use `#L10-L20` format for line ranges +### Referencing Issues and PRs + +When mentioning an Issue or PR in body text, always link it at the point of mention. + +- Write a full link, e.g. `[#123](https://github.com/org/repo/issues/123)` — never a bare `#123`, even within the same repository. A bare reference breaks the moment the text is copied outside GitHub +- Keep the link text to the number only. Embedding the title makes the link stale when the title changes +- Never paste a bare URL into body text +- A trailing "references" list is optional and never a substitute for linking at the point of mention + ### Scripts Require Tests When writing one-shot scripts (batch replacements, migrations, etc.), always write test code alongside them. diff --git a/dot_claude/references/writing_philosophy.md b/dot_claude/references/writing_philosophy.md index 1ee51e6..e62be06 100644 --- a/dot_claude/references/writing_philosophy.md +++ b/dot_claude/references/writing_philosophy.md @@ -57,7 +57,7 @@ ## 5. 知的誠実さを保つ - **限界を明示する** - この方法が万能ではないことを正直に書く -- **出典を示す** - 参考にした書籍・記事・ドキュメントを明記する +- **出典を示す** - 参考にした書籍・記事・ドキュメントを、言及した文の中でリンクにして明記する - **自分の理解であることを伝える** - 「以下は○○を参考に、私なりの理解を書いたものです」 読者に対する誠実さは、記事の信頼性の土台だ。 @@ -84,3 +84,19 @@ - **箇条書きは必要最低限に留める。** 列挙が本質的に必要な場合にのみ使う。流れのある説明は文章で書く - **見出しに数字を付けない。** 「1. はじめに」ではなく「はじめに」とする - **係り受けを明確にする。** 修飾語・被修飾語の関係を明確にし、読者が一度で理解できる文を作る + +## 9. 推敲ルール + +過去の記事推敲(RevOps AF 2026 参加記、150コミット超)で繰り返し指摘された機械的なパターン。執筆の時点でこれを守れば、推敲の往復が大幅に減る。 + +- **ダッシュ・横線記号(`──` `―` `—`)を使わない。** 読点・括弧・別の文に分けて表現する。引用の出典行にも使わない。英語原文の中の em dash はそのまま残す +- **区切り線(`---`)を使わない。** 構成の切れ目は見出しで表現する +- **直訳調を書かない。** 翻訳由来の内容は意味を取って平易な日本語に書き直す。「問題を探している解決策」「俯瞰」「直線的」のような輸入表現をそのまま使わない +- **不要なカタカナ語を自然な日本語に置き換える。** 定着した技術用語は除く +- **引用は「」で囲み、最低限に絞る。** 英語引用は原文でないと効かない箇所だけに残し、それ以外は日本語化する。帰属は記号を使わず話者名と文脈(セッション名など)を文章で書く +- **発言の引用は実際の発言に忠実にする。** 「言いそうなこと」を記憶で書かない。出典(文字起こし等)に当たって確認する +- **裏付けのない誇張をしない。** 「最大の」「初の」は裏付けの取れる表現に落とす +- **セクション間に橋渡しを入れる。** 唐突な概念の登場を避ける。ただし「同じテーマが繰り返し出てきました」のような中身のないつなぎ文は書かない +- **重複・冗長を削る。** 同じ主旨の段落は一箇所に集約する。全体の1〜2割は削れる前提で見直す +- **見出しにプレフィックスを付けず、階層をフラットに保つ。** 「前提:」「テーマ1:」のような接頭辞を避け、深い階層より並列の構成を選ぶ +- **出典は本文中でリンクにする。** 言及した文の中に Markdown リンクを置く。裸の番号・裸の URL を残さない。文末のリンク一覧だけで済ませない