davidvictor/build-in-public

Build in Public

概要

このスキルは、プロジェクトが既に動作しており、公開可能で安全かつ使いやすい状態にする作業が必要な場合に使用します。デフォルトのターゲットは~/.codex/workspaces/default/repos/または~/.codex/workspaces/default/labs/の下にあるサンドボックスリポジトリですが、同じワークフローは任意のローカルリポジトリで機能します。

リソース

• references/public-release-checklist.md 公開リリースゲートと最終完了パスに使用します。
• references/readme-template.md README.mdの作成または再構成時に使用します。
• scripts/create_release_zip.sh リポジトリの準備ができた後、現在の HEAD からクリーンなZIPを作成するために使用します。

ネイティブなCodex機能

ホストがネイティブなCodexアプリまたはCLI機能を提供する場合、それらを必須の依存関係にせずにアクセラレータとして使用します。

• 公開プラットフォームの事実、パッケージマネージャーの動作、セキュリティアドバイザリ、または変更された可能性のあるドキュメントについては、ウェブ検索を使用します。プライマリソースを優先し、最終レポートでそれらを引用します。
• リポジトリマップ、アーキテクチャ図、バナー、またはプロジェクトを理解しやすくするイラストアセットなど、READMEのビジュアルが必要な場合、組み込みの画像生成を使用します。画像を生成し、検査し、最終的に選択したファイルをリポジトリのassets/にコピーし、適切な場所のREADMEに挿入し、説明的なaltテキストを使用し、生成されたテキストが不完全な場合は重要な技術ラベルをMarkdown、Mermaid、SVG、または近くの散文に保持します。
• ローカルウェブプレビュー、ファイルベースのプレビュー、およびサインインを必要としない公開ページの視覚的レビューには、アプリ内ブラウザを使用します。
• プロジェクトがデスクトップアプリ、シミュレーターフロー、スプレッドシート、ドキュメント、プレゼンテーション、または通常のシェル/ブラウザツールでチェックできないその他のサーフェスである場合にのみ、コンピューター操作を狭いGUI検証に使用します。
• Codexアプリのワークツリーを、分離された探索的または並行リリース準備作業に使用し、その後、意図したファイルのみを公開レーンに昇格させます。
• ネイティブのGitレビュー、ステージング、コミット、プッシュ、およびPRサポートが利用可能な場合は使用しますが、それでも差分を検査し、ワーキングツリーに関係のないローカル状態がない状態に保ちます。
• 自動化は、定期的なリリースヘルスチェック、スケジュールされたメンテナンスレポート、またはフォローアップ監視にのみ使用します。一回限りの公開決定を定期的なバックグラウンド作業に変えないでください。
• ネイティブサブエージェントは、ユーザーまたはホストポリシーが並列委任を許可している場合にのみ使用し、リスク監査、ドキュメントレビュー、検証などの独立したレーンを、ファイルの所有権が重複しないように分割します。

デフォルトの成果

このスキルの終了時点で、リポジトリは次の状態になっている必要があります。

• 問題、なぜ構築されたのか、何をするのか、使用方法を明確に説明するREADME
• コールドリーダーのオリエンテーションを実質的に改善する場合の、オプションのプロジェクトバウンド図またはビジュアルアセット
• クリーンな公開用説明と推奨されるGitHubトピック
• セットアップ、エラー、無視ファイル、およびユーザー向けデフォルトの基本的な堅牢化
• メインパスと少なくとも1つのエッジケースまたは障害ケースを証明するテストまたはスモークチェック
• 必要に応じてライセンスと設定例
• コミットされたコードから作成されたクリーンなZIPアーティファクト
• ユーザーの個人プロフィール上の公開GitHubリポジトリ、または公開を待つべき正確なブロッカーの説明

リリース戦略

編集前に安全なレーンを選択します。

1. Git履歴、ファイルセット、および命名が既に公開しても安全な場合は、既存のリポジトリを再利用します。
2. ワーキングプロジェクトは良いが、既存のリポジトリにスクラッチ履歴、プライベートノート、実験的な残骸、または履歴内のシークレットがある場合は、クリーンな公開エクスポートリポジトリを作成します。

ルール：

• サンドボックスプロジェクトの場合、公開履歴に問題がある場合は、~/.codex/workspaces/default/repos/<slug>-publicのような兄弟公開リポジトリを優先します。
• 短いメモで来歴を保持しますが、プライベートパス、内部プロジェクト名、または個人のマシンの詳細を漏洩しないでください。
• 現在のリポジトリを安全にするために履歴の書き換えが必要な場合は、ユーザーが明示的に履歴の保存を希望しない限り、新しい公開エクスポートを優先します。
• リポジトリが見知らぬ人にとってコールドクローンから理解可能になるまでは、何も公開しないでください。

ワークフロー

1. 事前フライト

1. ターゲットリポジトリ、リモート、gitステータス、ビルドシステム、テストコマンド、およびスコープ内のすべてのAGENTS.mdを検査します。

2. references/public-release-checklist.mdを読みます。

3. READMEを作成または書き換える必要がある場合は、references/readme-template.mdを読みます。

4. インプレースで堅牢化するか、クリーンな公開エクスポートリポジトリを作成するかを決定します。

5. リポジトリ自体から、公開名、一行説明、インストールフロー、およびターゲットオーディエンスを推測します。それらが本当にあいまいな場合にのみ質問します。

6. リクエストがBuild in Publicである場合、公開先をユーザーの個人GitHub、可視性は公開にデフォルト設定します。

7. 現在の環境でどのネイティブCodex機能が利用可能かを確認し、最も軽量な有用なパスを選択します：決定論的なリポジトリ作業にはローカルシェル、現在の外部の事実にはウェブ検索、UI検証にはブラウザ/コンピューター操作、有用なビジュアルには画像生成、そして安全にスループットを向上させる場合にのみワークツリー/サブエージェントを使用します。

8. スパークを尋ねる。 何かを書く前に、コードを十分に深く読み、なぜこれが構築されたのかに関する3つの仮説を立てます。次にユーザーに尋ねます — 3つの最良の推測をオプションとして提示し、さらに全く別のもののための自由記述フィールドも提供します。

   何がきっかけでこれを作りましたか？

   1. [コードから導き出した最初の仮説]
   2. [2番目の仮説]
   3. [3番目の仮説]
   4. その他 — あなたの言葉で教えてください

   このパターンは、このスキル内のすべてのAskUserQuestion呼び出しに適用されます：既に読んだ内容に基づいて3つの具体的なオプションを常に提案し、ユーザーが上書きできる余地を残します。これは自由形式の質問よりも高速であり、あなたの仮説はしばしばユーザーが考慮していなかった枠組みを表面化させます。

   答えを文脈として扱い、福音として扱わないでください。ユーザーは自分の動機を知っていますが、技術的な興味を過小評価したり、デザインの実際に魅力的な点を見逃したり、狭くフレームしすぎたりする可能性があります。あなたの仕事はコードを読み、本当に話す価値があるものを見つけ、彼らの答えをレンズとして使用することです。コードが一次情報源です。彼らの答えはヒントです。

2. 公開リスクの監査

公開すべきでないものがないかリポジトリを検査します。

• シークレット、.envファイル、トークン、APIキー、プライベート認証情報、またはコピーされたシェル履歴
• 内部URL、個人のメールアドレス、絶対ローカルパス、マシン固有の手順、またはプライベートスクリーンショット
• 再配布できないプライベートデータセット、ベンダーアセット、またはサンプルファイル
• キャッシュ、ログ、生成されたデータベース、デバッグ出力、およびローカルのみのアーティファクト
• 間違ったストーリーを伝えたり、プライベートコンテキストを公開したりするスクラッチコミット履歴

ガイダンス：

• まず高速なローカル検査を使用します：rg、git status、git log、git ls-files、および対象を絞ったファイル読み取り。
• リスクがワーキングツリーにある場合は、それをクリーンアップします。
• リスクが履歴にのみある場合は、危険な履歴手術よりもクリーンなエクスポートリポジトリを優先します。

3. リポジトリの堅牢化

プロジェクトを他の人にとって使用可能にするための最小限の信頼できるパスを実行します。

• インストールと実行手順を決定論的にします
• 必要に応じてenv.example、サンプル設定、および無視ルールを追加または強化します
• エラーが読みやすく、デフォルトが適切になるようにプライマリエントリポイントを改善します
• 初めてのユーザーを混乱させる死んだ実験的な散らかりを削除します
• メインパスと少なくとも1つの障害またはエッジケースがカバーされるようにテストを追加または改善します
• 証明をプロダクトの形状に合わせます：
  • CLI：コマンドヘルプと実際のコマンドスモークテスト
  • ライブラリ：公開APIに関するユニットテスト
  • Webアプリ：メインフローのブラウザまたはリクエストレベルのスモーク
  • API/サービス：リクエスト-レスポンス証明とエラーハンドリングチェック
• リポジトリに既に自動化する価値のある簡単なコマンドがある場合にのみ、軽量なCIを追加します
• リポジトリまたはユーザーが明確に他の場所を指していない限り、ライセンスをMITにデフォルト設定します

これを大規模な書き換えにしないでください。「公開準備完了」とは、正直に共有できるほど洗練されていることであり、ゼロから再構築することではありません。

4. 公開ドキュメントの作成

見知らぬ人がすぐに方向性を把握できるように、公開向けドキュメントを作成または書き換えます。

• READMEの構造にはreferences/readme-template.mdを使用します
• 最初に問題を説明し、次にこのリポジトリが存在する理由、そして実行方法を説明します
• 新しいクローンから機能する具体的なクイックスタートパスを1つ含めます
• テストコマンドと必要なローカル依存関係を文書化します
• 現在の制限事項、プラットフォームの前提条件、または粗い部分について明示的にします
• 内部コンテキストを共有しすぎずにプロジェクトの起源を説明する短いBuild in Publicノートを含めます
• コールドリーダーがファイルレイアウト、データフロー、またはユーザーワークフローを理解するのに役立つ場合、ビジュアルリポジトリマップまたはアーキテクチャ図を含めます。正確なラベルにはMermaidまたはリポジトリネイティブの図を優先し、洗練されたダークモードのイラスト、バナー、または補助ビジュアルにはネイティブ画像生成を使用します。
• 準備します：
  • 一行のGitHub説明
  • 短いトピックリスト
  • ユーザーが最初のリリースを希望する場合のオプションのリリースノート

ASCIIバナーを生成します。 すべてのREADMEは、すべての上、一番上にfigletバナーを取得します。rectanglesフォントを使用します — 斜体の文字はありません。実行します。

figlet -f rectangles -w 200 "<バナーテキスト>"

バナーテキストのルール：

• リポジトリのスラッグではなく、プロジェクトの表示名を使用します
• ハイフンをスペースに置き換えます（build-in-public → build in public）
• すべて小文字にします（Mock Pop → mock pop）
• 表示名がリポジトリスラッグと異なる場合（例：リポジトリ superwhisperer-lab、表示名 superwhisper lab）、表示名を使用します

出力をフェンスで囲まれたコードブロックでラップします。figletがインストールされていない場合：brew install figlet。これは誰かが見る最初のものです — プロジェクトに実際のアイデンティティがあることを示します。

READMEビジュアルを生成して配置します。 生成された画像がREADMEに属する場合、それを一時的なプレビューではなく、コミットされたプロジェクトアーティファクトとして扱います。

1. 画像の役割と配置を、生成する前に決定します。

   • リポジトリ全体の概要、アーキテクチャマップ、またはヒーロービジュアル：README.mdの上部近く、タイトルと一行要約の直後、またはその方が読みやすい場合は短い冒頭段落の後に配置します
   • 機能のスクリーンショットまたはワークフロー画像：それが説明するセクション、詳細な散文またはサポートする例の前に配置します
   • 補足画像：READMEの下部に配置するか、何も明確にしない場合は省略します

2. ネイティブなCodex画像生成が利用可能な場合はそれを使用して画像を生成し、正確なテキストや決定論的な構造がより重要な場合はMermaid/SVG/リポジトリネイティブの出力を使用します。

3. 結果を可読性、歪んだラベル、プライベート情報、およびそれが実際にプロジェクトを明確にしているかどうかを検査します。

4. 最終的に選択した画像をリポジトリにコピーします。通常はassets/<説明的な名前>.<拡張子>またはdocs/assets/<説明的な名前>.<拡張子>に配置します。READMEで参照されるアセットを、生成画像ディレクトリ、ダウンロード、テンポラリ、またはローカルキャッシュディレクトリにのみ残さないでください。

5. 画像をREADME.mdに相対パスと意味のあるaltテキストで挿入します。

   ![ダークモードリポジトリ構造図](assets/repo-structure-dark.png)
   

6. 画像とREADMEの更新を一緒にコミットして、パスがクローン、フォーク、GitHubレンダリング、およびリリースZIPで有効になるようにします。

7. ビジュアルが再生成される場合、READMEが常に最新の画像を表示する必要がある場合は安定したファイル名を使用し、以前の出力を保存することが重要な場合はバージョン管理されたファイル名を使用します。再現性が重要な場合は、生成プロンプト、ソース図、またはスクリプトをリポジトリに保持します。

コードからナラティブを構築し、ユーザーから情報を得ます。 ユーザーのスパーク回答はコンテキストです — それを使用して意図を理解しますが、彼らのストーリーを逐語的に書くためではありません。本当のナラティブはコードを注意深く読むことから来ます：デザインが実際に解決する問題は何か、明白でない決定は何か、ピア開発者が興味深い、または盗む価値があると感じるものは何か。

ナレーターとしてのあなたの仕事：

• コードの中で実際に興味深いものを見つけてください — デザインを形成した制約、明白な解決策とは異なるアプローチ、意図的になされたトレードオフ
• 問題を適切な具体性のレベルでフレームします。同じフラストレーションを持った誰かが認識できるほど具体的であり、ユーザーの正確なマシンだけに関するものではないほど一般的です
• 声を与えてください — 誇大広告でもマーケティングコピーでもなく、実際に厄介な何かを解決し、その方法を伝えたいと思っている開発者の明確で少し興奮したトーンです

ユーザーの説明が浅い場合（「ただ動けばよかった」）、コードを掘り下げて自分で本当のストーリーを見つけてください。彼らの説明がコードが保証するよりも技術的に豊かな場合は、引き戻してください。READ MEはプロジェクトが何であるかについて正直であるべきです — 小さな、便利で、よくできたツール — 過大評価しないでください。

トーンは次のとおりです：「ここに実際の問題がある、ここに私が構築したものがある、ここにそれがどのように機能するかについて興味深い点がある。」小さなツールでも良いストーリーがあります。それらを平坦化しないでください。しかし、膨らませもしないでください。

ドキュメントの散乱を避けてください。強力なREADME、ライセンス、および最小限のサポートファイルは、儀式的なドキュメントの山に勝ります。

5. 検証とパッケージ化

リポジトリが合理的にサポートできる最強の検証を実行します。

1. 関連するインストール、ビルド、リンター、テスト、およびスモークコマンドを実行します。
2. クイックスタートの手順を実際のコードに対して検証します。
3. 実用的であれば、現在のマシン状態を信頼するのではなく、コールドクローンパスをシミュレートします。
4. Webまたはビジュアルサーフェスの場合、利用可能な場合はアプリ内ブラウザを使用し、検証結果をレポートにキャプチャします。
5. GUIのみのサーフェスの場合、コンピューター操作を狭く使用し、何をチェックしたかを記録します。
6. コミットされたコードから公開用ZIPアーティファクトを作成します。

bash "$(dirname "$0")/scripts/create_release_zip.sh" <リポジトリパス>
# またはインストールされたスキルから：
#   bash ~/.claude/skills/build-in-public/scripts/create_release_zip.sh <リポジトリパス>   # Claude Code
#   bash ~/.codex/skills/build-in-public/scripts/create_release_zip.sh <リポジトリパス>    # Codex

ヘルパーはZIPを~/.codex/worksp...の下に書き込みます。

（注意：元のSKILL.mdで切り詰められたため、ここでマークダウンは終了します。必要に応じて追加のセクションを翻訳のために提供できます。）

6. 公開と報告

（スキルのこのセクションは提供されたSKILL.mdに完全には含まれていませんが、公開GitHubリポジトリの作成と実行されたアクションを文書化した最終報告書の生成が含まれます。）