このガイドは、Blueskyのデベロッパー・リレーションズ担当ジム・レイ氏（@jimray.locket.computer）が2026年4月に開催するBluesky Hackathon in Tokyo Vol. 1のために書いた文章を、許可のもとに翻訳したものです。

なおBluesky Hackathon in Tokyo Vol.1 は 2026/4/18 開催の予定となります。参加者募集中！！エンジニアのほか、デザイナーやアイデア出す人、取りまとめる人、発表する人…様々な役割が必要です！「エンジニアじゃないけど…」と思っても興味があったら是非ご参加ください！

https://428lab.connpass.com/event/387583/

⚠️ 注意しておきたいこと

一般的な免責事項および注意事項として、atproto内の公開データはグローバルに配信されます。本プロトコルでは、コンテンツの可視性を制限する機能はまだサポートされていません。つまり、プロジェクトを設計する際にも、エンドユーザーに伝える際にも、細心の注意を払う必要があります。

はじめに

Atprotoは、大きな世界に広がるオープンなソーシャルプロトコルです。ユーザーはJSONレコードをリポジトリに公開します。その後、それらのレコードの変更内容がネットワーク全体で同期され、アプリケーションを駆動します。

コミュニティメンバーであるダン・アブラモフによる以下の素晴らしい記事をお勧めします。

Open Social プロトコル自体がAPIである。
Where it's at:// ハンドルからホスティングまで。
A Social Filesystem アプリケーションよりもフォーマット。

完全なドキュメントは https://atproto.com/docs で入手できます

Atproto上では、既存のインフラストラクチャ、ツール、ユーザーコミュニティを利用して、まったく新しいソーシャルアプリを構築することが可能です。現時点では、他のアプリよりも適しているアプリもあります。ここでは、今日成功する可能性があると考えるいくつかのパターンを紹介します。Statusphere Tutorial と、「What does an AppView Implementation Entail」を参照して、完全なアプリケーションを構築するために必要なものの概要を確認してください。

レビューとレコメンデーション: Atprotoモデルに非常に適合するソーシャルアプリの幅広いカテゴリーとして、ほぼあらゆる種類の施設、コンテンツ、または製品（レストランやイベント会場、企業やサービス、映画やその他のメディア、耐久消費財やハイテク製品など）を対象としたソーシャルレビューおよびレコメンデーションサービスが挙げられます。モデレーション機能（ラベリングやOzoneなど）を活用することで、偽アカウントや評価の操作を抑制することができます。既存のデータベースや識別子（例：IMDB、MusicBrainz、Wikidata、ISBN、SKU）を活用することで、対象の曖昧性を解消できます。また、既存のソーシャルグラフ（Blueskyのフォロワーグラフなど）を活用することで、ソーシャルレコメンデーションの初期構築が可能となります。

質問と回答: 共同ナレッジベース、またはよりカジュアル/ローカルなアドバイスといったものにも適しています。

長文コンテンツ: Atprotoでブログを実装している素晴らしいプロジェクトがすでにいくつかあります。Leaflet、pckt、Offprint などです。より具体的な記事やエッセイの形式は、カスタムインターフェイスとスキーマの恩恵を受ける可能性があります。学術論文、インタラクティブな調査、旅行記や地域ガイド、ルートの説明、技術文書、写真集のような雑誌記事などです。多くの長文アプリケーションは、データエンコーディングのためにstandard.siteのLexiconを使用しています。

SDKとツール

さまざまなプログラミング言語に対応した、多くのファーストパーティおよびコミュニティツールが https://atproto.com/sdks で入手できます。

Claude Codeとatprotoの利用

Claude Codeはatprotoの開発を大幅に加速させることができますが、その使い方を理解することと同様に、どこで役立つか、どこで誤った結果を出してしまうかを把握することも重要です。

atprotoのスキーマシステムであるLexiconは、レコード型、HTTPエンドポイント、イベントストリームメッセージを記述する、機械可読なJSONです。すべてのフィールドには明示的な型、検証制約、および必須/オプションのフラグが設定されています。これにより、Lexiconはコード生成に適した入力となります。文章によるドキュメントとは異なり、エージェントが誤って解釈するような曖昧さがほとんどないからです。

活用のヒント

Lexicon GardenでLexiconを見つける。 コミュニティサイトlexicon.gardenでは、新しいレキシコンを閲覧・発見することができます。さらに便利なことに、各レキシコンには対応するLLMテキストファイルが用意されており、これをAIツールに直接渡すことができます。app.bsky.feed.like用のLLMテキストファイルはこちらです。

Claude Codeには、Lexiconファイルの説明ではなく、ファイルそのものを直接渡す。LexiconのJSONをコンテキストとして貼り付けてください。エージェントが文章（「ステータスフィールドが絵文字になっているレコードが欲しい」）を基に処理を行う場合、フィールド名や型を推測することになり、時に誤った判断を下すことがあります。Lexiconを基に処理を行う場合、実際のスキーマが使用されます。これはファイアホース・コンシューマーの生成にも有効です。各レコードの$typeフィールドにより、Claudeは明示的に指定されなくてもレコードの種類を識別し、フィルタリングすることができます。

リポジトリ操作のコアとなるLexiconも含める。完全なRead/Writeクライアントが必要な場合は、独自のLexiconに加えて、com.atproto.repo.* のLexiconをClaudeに提供してください。これらは、アプリが使用するXRPCメソッド（putRecord, getRecord, listRecords）を定義します。これらがなければ、Claudeはメソッドのシグネチャを推測することになります。これらはatprotoのモノレポ内にあります。

OAuthは明示的に指定する。アプリをスケルトン化する場合、Claudeはアプリパスワードを使用してcreateSessionを呼び出そうとする可能性があります。これは、古いチュートリアルやトレーニングデータでよく見られるレガシーなパターンです。そうしないよう、明確に指示してください。OAuthクライアント実装ガイド、またはTypeScript SDKのOAuthパッケージ（@atproto/oauth-client-browser または @atproto/oauth-client-node）を参照させるようにしてください。SDKがディスカバリー、PKCE、DPoPトークンのバインディングを処理します。その上に、Claudeにアプリケーションロジックを記述させましょう。

FirehoseコンシューマーにはJetstreamを使用する。生のRelay WebSocketストリームは、CARファイル形式でエンコードされたリポジトリイベントを送信しますが、レコードを抽出するにはMerkle Search Treeの解析が必要です。JetstreamはFirehoseを整理されたJSONに変換するため、扱いがはるかに簡単です。ClaudeはJetstream用のコンシューマーを初回から正しく生成しますが、生のRelay形式の場合は事情が異なります。

Claude Codeが苦手な点

新しいLexiconの設計。Claudeは構文的には正しいLexicon JSONを生成しますが、意味論的な側面、例えばNSIDの権限（xyz.statusphere.statusにあるドメインは、権限がstatusphere.xyz であることを意味します）、キー戦略の選択、スキーマの進化に関する制約（フィールドの名前変更や型の変更はできず、互換性を破る変更を行うには新しいNSIDが必要となります）といったことを見落とすことが多いです。Lexiconはご自身で設計し、Claudeを使ってそれに基づいて実装してください。

リッチテキストのファセット。app.bsky.feed.postレコードのファセットバイト範囲は、文字位置ではなく UTF-8 エンコードされたバイトに基づいてインデックス化されます。Claudeは約半数のケースで、文字ベースのインデックスを持つコードを生成します。ファセットを手動で作成するのではなく、SDKのRichTextヘルパーを使用してください。

PDSとAppViewの区別。 Claude、PDS（ユーザーデータが格納されている場所）とAppView（アプリケーションからのクエリ用にデータがインデックス化されている場所）を混同しがちです。PDSからフィードやソーシャルグラフのデータを取得しようとするコードは動作しません。それらはAppViewに存在します。