sync-upstream

upstream との同期

このリポジトリは、mattpocock/skills をブラジルポルトガル語向けに適応したものです。目的は逐語訳ではありません。各 skill は、元の目的、動作、フロー、意図を保ちながら、ブラジルの読者に適した表現、例、文脈で作成されています。

upstream は semver リリースでバージョン管理されており、各変更を説明する CHANGELOG.md が用意されています。同期はリリースごとに行い、ブランチを継続的に追跡することはありません。

正式な情報源

このリポジトリのルートにある UPSTREAM.md：

• upstream-version: — 同期が完了した upstream の最後のタグ。
• 意図的な名前変更の対応表（このプロジェクト固有のもの）。
• このリポジトリ専用の skills（削除禁止 — upstream に対応するものはありません）。
• 既知の未対応項目。

remote upstream は Matt のリポジトリを指します。存在しない場合は、次を実行します：git remote add upstream https://github.com/mattpocock/skills.git。

タグの名前空間

upstream のタグは upstream/*（例：upstream/v1.1.0）の下に置かれます。vX.Y.Z の名前空間はこのリポジトリのリリース用です。これにより、Matt の同名タグと衝突せずに同期のタグを付けられます。

remote はすでにこのように設定されています。新しい clone で設定されていない場合：

git config remote.upstream.tagOpt --no-tags
git config --add remote.upstream.fetch "+refs/tags/*:refs/tags/upstream/*"

決して git fetch upstream --tags を実行しないでください。Matt のタグがそのままの名前空間に取り込まれ、衝突が再発します。

手順

1. 差分を確認する

git fetch upstream

• BASE = UPSTREAM.md の upstream-version: の値（例：v1.1.0）。upstream/$BASE として読み込みます。
• ALVO = upstream の最新タグ：git tag -l 'upstream/v*' | sort -V | tail -1。
• BASE == ALVO → 対応は不要です。終了してください。

2. 変更を把握する — まず CHANGELOG、次に diff

1. upstream の CHANGELOG.md から BASE と ALVO の間のセクションを読みます（git show upstream/$ALVO:CHANGELOG.md）。何が変わったのか**、そしてその理由**が説明されています。レポートの骨子として使い、ゼロから作り直さないでください。

2. rename の検出を有効にして、実際の diff を生成します：

   git diff -M upstream/$BASE..upstream/$ALVO -- skills/ .claude-plugin/plugin.json
   

   docs/ は意図的に対象外です。意図的な差異については UPSTREAM.md を参照してください。

3. diff と UPSTREAM.md の名前の対応表を照合します（例：setup-matt-pocock-skills の変更は setup-leandrocfe-skills に適用します）。

3. レポートと提案 — ファイルに手を加える前に

メンテナーに次の内容を提示します：

• 変更をカテゴリ別にまとめたもの（新しい skills、rename、変更、削除）。
• 各項目について、何が変わったか、なぜ重要か（CHANGELOG を引用）、今回のバージョンへの影響。
• 以下のルールに従った適応案。
• 人による判断が必要な点を明示したもの。

ここで停止し、承認を待ってください。 曖昧さがある場合、バージョン間で競合する場合、または適応方法が複数ある場合は、先に質問してから続行してください。

4. 適用 — 承認後に限る

• skill ごとに適応し、コピー＆ペーストはしないでください。
• UPSTREAM.md の対応表に記載されたものを除き、upstream の rename は git mv で反映します。
• .claude-plugin/plugin.json を更新します。skills の一覧は実際のディレクトリと一致させ、version フィールドは同期対象のタグと一致させてください。「ARS scope guard」フックにより、エージェントはこのファイルを書き込めません。メンテナーに内容を渡して手作業で保存してもらうか、フックを無効にするよう依頼してください。
• upstream の skills を連鎖して参照している、このリポジトリ専用の skills（personal/）を確認します。rename によって、これらの参照が気づかないうちに壊れることがあります。
• 最後に検証します：plugin.json の各項目が skills/ に存在すること、frontmatter の name: がディレクトリ名と一致していること、削除済みの skill 名への参照が残っていないこと（古い名前を grep すること）、バケットとトップレベルの README が CLAUDE.md に従って更新されていること。

5. 同期を完了する

1. UPSTREAM.md の upstream-version: を ALVO に更新し、解決済みの未完了項目を削除します。
2. コミットします：sync: upstream ALVO。
3. upstream のバージョンに合わせて、このリポジトリのリリースタグを付けます：git tag -a $ALVO -m "sync: upstream $ALVO"。Matt のタグは upstream/* にあるため、通常の名前空間は空いています。
4. git push origin $ALVO を実行する前に、メンテナーにプッシュの承認を確認します。
5. ワークフローによって作成された同期用の Issue があれば、クローズします。
6. 任意：CHANGELOG のリリースセクションを翻訳し、このリポジトリのリリースノートとして公開します。

適応ルール

• upstream の内容を自動的にコピーしないでください。
• このプロジェクトのアイデンティティ（UPSTREAM.md でマッピングされた名称）を維持してください。
• ブラジルポルトガル語で記述し、定着している技術用語は英語のままにしてください。
• プロフェッショナルで洗練された文体にしてください。 スラング、口語表現、無理にくだけた言い回しは避けてください（例：「UX gostosa」「sacada」「dá pra」「maneiro」）。技術文書にふさわしい、構成が明確で読みやすいポルトガル語に訳してください。表現の効果よりも正確な用語を優先してください。原文の宣伝調の形容詞（「delightful」「beautiful」など）は、俗語ではなく、落ち着いた表現（「refinada」「bem-acabada」など）に置き換えてください。迷った場合は声に出して読み、技術マニュアルとして不自然に聞こえるなら書き直してください。
• 同じ文言を再現することではなく、スキルの動作と意図を優先してください。
• Matt の実情に強く依存する具体例は、適切であればブラジルの状況に合う例を提案してください。
• このリポジトリに既存のカスタマイズがある場合は、upstream の重要な改善と競合しない限り維持してください。競合する場合は、手順 3 のレポートでその競合を指摘してください。
• UPSTREAM.md に記載された、このリポジトリ固有のスキルは決して削除しないでください。

自動同期ではなく、慎重で根拠の明確な更新を優先してください。提案を適用する前に、それぞれの理由を説明してください。