workspace

ワークスペース

研究プロジェクトの執筆・ドキュメント作成を管理します。必要に応じてインフラを構築し、レンダリング結果を表示して、各イテレーションを保存します。研究タスクのグラフ自体（型付きタスクの計画・実行）を管理するには、asta-flows を使用してください。

assets/DEVELOPER.md は共通の開発者ガイドです。プロジェクトごとに一般的な手順をコピーするのではなく、選択した asta-plugins の ref にあるプロジェクトの README からリンクしてください。この SKILL.md はエージェント固有の手順です。

レンダリング結果をユーザーに表示する

レンダリング結果を表示するウェブ URL をユーザーに案内してください。URL の取得元は 2 つあります。状況に応じて選択してください。

• ローカルエージェント（ホスト、ローカル開発コンテナー、または Codespace — ユーザーがポートにアクセスできる場合）：バックグラウンドで make preview を実行します。Quarto が出力する URL を渡してください（ホスト／開発コンテナーでは localhost、Codespace では Codespaces で転送された URL）。
• ヘッドレスエージェント（ユーザーがアクセスできるポートがない場合）：ブランチをプッシュ（保存を参照）してから、make deployed-url を実行し、GitHub Pages CI からデプロイ済みの URL を取得します。

以前のバージョンからの変更点をユーザーが確認したい場合は、asta workspace what-changed <ref>（Git 2.30 以降）を案内してください。指定した ref で、プライベートな作業ツリーのコピー内においてプロジェクトの make render を実行し、PR プレビューの差分スクリプトを再利用します。公開先は .asta/cache/what-changed/ のみです。ライブプレビューは開いたままにできます。バックグラウンドで asta workspace preview --what-changed を実行し、ポート 4849 の URL（localhost または Codespaces で転送された URL）をユーザーに案内してください。実行中のサーバーは、その後の比較も反映します。PR も Pages へのデプロイも不要です。最後に読んだバージョンの記録はユーザーが管理します。読み終えたら git tag -f last-read を実行するよう提案してください。

信頼できる ref を選び、コピーの作成中はソースファイルを変更しないでください。ベースラインに含まれるのはコミット済みファイルのみです。現在の無視対象の入力ファイルを過去のデータとして提示しないでください。比較は一度に 1 つずつ実行してください。ビルドの前提条件、コピーにかかるコスト、クリーンアップ、配信上の制限については、開発者ガイドを参照してください。

論文の変更を反映する前に

論文の PR をマージする前、または許可されている場合に論文の編集内容をデフォルトブランチへ直接プッシュする前に、asta:overleaf-sync ラベルが付いたオープン中の PR があるか確認してください。まずその PR をマージし、共著者による新しい編集が反映される際に、マージ前にあなたの変更と競合するようにしてください。同期が追いついていない場合は、Overleaf トークンが利用可能な場所で asta workspace overleaf sync --wait 1800 を実行し（バックグラウンドでもかまいません。最終的な Sync outcome: 行と終了コードに基づいて対応してください）、その後ブランチを更新してください。論文を編集する前と、論文の PR をマージした後にも、同じ方法で同期してください。同期の競合はその PR で解決し、チェックを再実行してください。.asta/overleaf のペアリング記録を手動で進めて回避してはいけません。 スケジュール調整、招待された共著者のアクセス、ロックの復旧、リポジトリのステータスについては、Overleaf 同期を参照してください。

保存

git add + git commit -m "<concise message>" を実行します。ユーザーの明示的な承認なしに git push しないでください。

ワークスペースの PR を作成する前に、ローカルエージェントとヘッドレスエージェントのどちらでも、ピンを最新の状態に保ちます。

1. 作業をコミットし、make check を実行して、成功したかどうかを記録します。
2. asta workspace bump-pin を実行し、エラーがあれば報告して、表示された復旧メッセージに従います。bump を実行すると Committed <sha> が表示されます。
3. SHA が表示された場合は、make check をもう一度実行します。ビルドがその前は成功していて、今は失敗する場合は、git revert --no-edit <sha> を実行し、bump なしで続行します。

ヘッドレスエージェントの場合（ユーザーがデプロイ済み URL 経由でのみ結果を確認する場合）：

• リポジトリが空の場合は main を初期化します。 コミットがないリポジトリでは、最初にプッシュされたブランチがデフォルトになります。すると、PR の作成先となる main がなくなります。git ls-remote --heads origin main で確認します。存在しない場合は、最初のコミットとともにリポジトリを作成する方法（GitHub の 「Add a README file」、または gh repo create <owner>/<name> --add-readme）を優先し、最初から main が存在するようにします。それができない場合は、git push -u origin HEAD:main で初期化します（確認すべき既存状態がないため、これは正当です）。
• 最初の保存時：ピンを最新の状態に保ち（上記参照）、git push -u origin HEAD:<feature-branch>、gh pr create --fill の順に実行し、その後 make deployed-url を実行して URL を報告します。
• 2 回目以降の保存時：git push、make deployed-url の順に実行します。
• マージの明示的な承認を得た後：gh pr merge を実行し、make deployed-url を実行します。

ユーザーの明示的な承認なしに PR をマージしないでください。

Overleaf 同期の拒否

asta workspace overleaf pull または publish が拒否された場合、あるいは同期 PR で競合が発生した場合は、そのメッセージからリンクされている workflows/overleaf-recovery.md のセクションに従います。

必要に応じてスキャフォールドのコンポーネントを追加

コンポーネントは必要な場合にのみ追加し、先回りして提案しないでください。

コンポーネント	追加するタイミング
Quarto build tool	常に追加します。これはプロジェクト構造の一部です。
Version workflow stub	マネージドルールでは常に追加します。Pages の自動デプロイは必要な場合にのみ有効にします。
GitHub Pages deploy	ユーザーがアクセス可能なポートがない場合、またはデプロイ済み URL をユーザーが求めた場合に追加します。
Dev container	ホストの依存関係のインストールを避けたい場合、または別のマシンからブラウザーのみでアクセスしたい場合に追加します。2 つのフローについてはサブセクションを参照してください。

以下の手順でファイルを書き込む前に、対象のパスがすでに存在するか確認します。存在する場合は、上書きする前にユーザーに確認するか、アセットの内容を既存のファイルに統合します。

Quarto ビルドツール

1. assets/_quarto.yml をプロジェクトのルートにコピーし、{{TITLE}} と {{REPO_URL}} を入力します （https://github.com/{owner}/{repo} のような正規の GitHub URL を使用します）。
2. title: フロントマターを含む index.qmd を作成します。
3. 空の references.bib を作成します。
4. assets/evidence.yml をプロジェクトのルートにコピーします（キー付きの引用保存ファイルです。空のままでも保持してください）。Makefile は各レンダリングの前に、このリポジトリからエビデンス拡張機能と Asta テーマを取得します。拡張機能のディレクトリをコピーせず、どちらも管理対象のままにしてください。スキャフォールドは、読者のシステム設定にかかわらずダークモードで開き、ライトモードへの切り替えを常時表示します。どちらのモードも同じタイポグラフィとレイアウトを使用し、長いページではセクション見出しが固定表示されます。プロジェクト独自の theme: と CSS はそのまま保持してください。カスタマイズについては、開発者ガイドの サイトの外観 セクションを参照してください。以下の 裏付けとなるエビデンスで主張を支える も参照してください。
5. assets/gitignore のうち、プロジェクトの .gitignore にない行を追加します（存在しない場合は作成し、既存の項目は上書きしないでください）。
6. assets/Makefile.managed を Makefile としてコピーします。共有ルールとスクリプトは asta workspace sync によって、無視対象の .asta/cache/ に取得されます。ユーザーがカスタマイズを希望しない限り、scripts/ を作成したりヘルパーをコピーしたりしないでください。プロジェクトが所有する workspace.mk または scripts/<name> が優先されます。スキャフォールドを導入する際は、既存のプロジェクトターゲットを保持してください。
7. ローカル専用のプロジェクトであっても、薄い assets/docs.yml ワークフローのスタブを追加します。ローカル専用で使用する場合は、on.push と on.pull_request イベントを削除し、on.workflow_dispatch を使用して、公開に手動での有効化が必要となるようにします。jobs.docs.uses の行は保持してください。同期時に読み取られます。既存のバージョンポリシー（@main のカナリア、@latest のリリースチャネル、または固定されたリリース／コミット）は維持してください。無関係なセットアップの一環としてアップグレードしたり、再固定したりしないでください。
8. assets/README.md をコピーし、{{TITLE}}、{{DESCRIPTION}}、{{ASTA_PLUGINS_REF}} を入力します。ガイドへのリンクには .github/workflows/docs.yml の ref を使用します。上流の latest ブランチはリリース済みのガイドを追跡します。カスタム ref の場合はリンクを確認してください。
9. asta workspace sync --require-scripts を実行し、その後 make check を実行します。カスタマイズしたコピーは保持してください。古い未変更のヘルパーを削除する前に、正常に更新できることを確認し、空のキャッシュからプロジェクトを検証してください。
10. Overleaf プロジェクトと論文を同期した状態に保つには、workflows/overleaf-sync.md に従ってください。

独立した LaTeX 論文（任意）

ユーザーが LaTeX を直接記述したい場合にのみ追加します。Quarto から PDF への変換は、必要に応じて quarto render <page>.qmd --to pdf を実行します。生成された .tex、PDF、HTML、ビューアーページは作成またはコミットしないでください。

1. assets/paper/main.tex と assets/paper/latexmkrc を paper/（または選択した論文ディレクトリ）にコピーし、既存の論文ソースとエンジン設定は保持します。{{TITLE}} を埋め、&、%、_、#、$、波括弧、バックスラッシュなど、LaTeX の特殊文字をエスケープします。論文ディレクトリからビルドすると、rc は Git ルートで停止するまで上位ディレクトリを検索して references.bib を探します。参考文献が利用可能になったら引用を追加し、スターターの参考文献行のコメントを解除します。空のプロジェクトは参考文献リストなしでビルドできます。独立した論文の執筆内容は Quarto ページから切り離しておきます。project.md は asta-assistant の brainstorm に属するものであり、このスキャフォールドのものではありません。
2. assets/paper/gitignore の不足しているエントリーを .gitignore に追加し、{{PAPER_DIR}} を選択した相対ディレクトリ（デフォルトでは paper）に置き換えます。ネストされたディレクトリを含め、論文ごとに繰り返します。ディレクトリ名に含まれる Git ignore パターン文字はエスケープします。ソースと rc はコミットし、ビルド出力と生成されたビューアーは無視します。カスタムビューアーがコミットされている場合は、ignore ルールが削除された後もそちらが優先されます。
3. 開発コンテナーでは -tex イメージを使用します。TeX、LaTeX Workshop、エディターのデフォルト設定が含まれています。.vscode/settings.json はコピーしないでください。イメージを選ぶ際は、プロジェクトで選択済みのバージョン／チャネルを維持します。
4. 共通ルールでは make paper と make paper-clean が使えます。PAPER_DIR=<directory> で別の論文を指定します。古い ref を使用している既存プロジェクトは、これらのルールが提供される ref にアップグレードするまで、独自のターゲットを維持できます。プロジェクトではターゲットをオーバーライドするか、workspace.mk を切り離して使用できます。
5. 管理対象のビューアーは <paper-dir>/html/index.qmd です。プロジェクトに明示的なレンダー許可リストがある場合にのみ、これを project.render に追加し、サイトから <paper-dir>/html/index.html にリンクします。既存のページリストやナビバーの項目は維持します。共通ビューアー生成機能が必要な JavaScript リソースを処理するため、ビューアーのソースはコミットしないでください。
6. make paper（デフォルト以外のディレクトリの場合は PAPER_DIR を指定）と make check を実行します。選択したリリース済みルールでまだ paper が提供されていない場合は、選択したディレクトリで (cd paper && latexmk -synctex=1 -interaction=nonstopmode -halt-on-error -file-line-error -outdir=build main.tex) を実行するか、代わりに LaTeX Workshop を使用します。プロジェクトの ref を黙って変更したり、Make レシピをコピーして追加したりしないでください。これらの古い ref でも、共通 CI の論文プレビューはすでに機能します。Pages が有効な場合は、PR プレビューの論文 PDF、論文ページ、What changed を確認します。1 つの TeX イメージで複数の論文に対応します。検出機能は、latexmkrc が隣接する main.tex をネストされたディレクトリも含めて探します。

主張を裏付ける証拠を添える

スキャフォールドは、ずれが生じる可能性のあるコピーをリポジトリに含めるのではなく、各レンダリングの前に asta-plugins から小さな Quarto 拡張機能（_extensions/evidence/）を取得します。管理対象のプロジェクトでは、.github/workflows/docs.yml で選択した参照先を使います。アップグレードするには、その参照先だけを変更して make update-workspace を実行してください。単独で切り離された Makefile では、ASTA_PLUGINS_REF を個別に設定できます。この拡張機能を使うと、本文中の事実に関する主張に、その裏付けとなる証拠を添えられます。主張には控えめな点線の下線が付き、ホバーするかキーボードでフォーカスすると、引用文と本文スタイルの出典が表示されます。純粋な CSS でレンダリングされるため、what-changed 差分ページにも表示され、レビュアーは差分を離れずに各主張の裏付けを確認できます。

調査して書いた主張には、裏付けを添えてください。evidence.yml にキー付きのエントリーを追加し、一字一句そのままの引用文、その cite キー（論文を references.bib に追加してください）、任意の native citeproc locator（p. 4、sec. 3.2、abstract など）、および任意の provenance: を記載します。Provenance には、実際に確認した事実のみを記録してください。method には正確な CLI サブコマンド（例：asta papers snippet-search）を使い、url にはインデックス済みの Asta ドキュメントに対して返された正規の asta:// URI を使います。スキル名や生成者名を推測せず、不明なフィールドは省略してください。そのうえで、.qmd に主張をマークします。

NatureBench has [90 tasks]{.ev key="naturebench-count"}.

quote: に記載できるのは、一字一句そのままの引用文だけです。言い換えのモードはありません。自分の言葉で書いた内容は本文に記載してください。フィールドの完全なリファレンスと設計上の説明は _extensions/evidence/README.md にあります。

これらのエントリーの構造検証は、決定論的なビルドツールで行います。主張にそもそも証拠が必要かどうか、また引用文がその表現どおりの主張を実際に裏付けているかどうかは、判断を要します。そのためには check-claims スキルを読み込み、PR を開く前と、レビューする際の両方で確認してください。

GitHub Pages へのデプロイ

1. assets/docs.yml を .github/workflows/docs.yml にコピーします。これは薄いスタブです。ビルド／デプロイ／プレビューの仕組みは、このリポジトリの再利用可能なワークフロー（.github/workflows/workspace-quarto-site.yml）にあるため、スキャフォールドされたプロジェクトは再コピーせずに修正を取り込めます。プロジェクト固有の品質ゲートは、再利用可能なワークフローから呼び出されるプロジェクトの make check ターゲットに記述します。既存のプロジェクトをこのスタブに更新する際は、同じ変更で Makefile も更新してください（ワークフローには check ターゲットが必要です）。また、ブランチ保護で必須にしているチェック名を新しいコンテキストに更新してください（ビルドチェックは docs / build として報告されます）。gh api で試し、GitHub に拒否された場合は、ユーザーにコマンドを伝えてください。
2. 提供されている assets/github-pages.json を使って、Pages が gh-pages から配信するように設定します。gh api repos/{owner}/{repo}/pages -X POST --input <skill-dir>/assets/github-pages.json を実行してください。GitHub に拒否された場合は、そのコマンド、ファイル、および GitHub のエラーをユーザーに伝えてください。gh api repos/{owner}/{repo}/pages で設定を読み戻し、ソースが一致することを確認してください。Pages がすでに別のソースで設定されている場合は、ユーザーに伝えてください。
3. 任意。このリポジトリを含め、セットアップする GitHub リポジトリでは、リポジトリの保護（デフォルトブランチのルールセット、必須のドキュメントチェック）を推奨してください。提案または適用する前に、workflows/repo-protections.md を読み、その指示に従ってください。

すべての PR で、ワークフローはレンダリング済みの完全なプレビューを <pages>/pr-preview/pr-<N>/ に、その隣に what-changed.html を公開します。後者は、デプロイ済みのベースサイトと比較して、レンダリング結果の追加箇所と削除箇所を強調表示し、変更のないセクションを折りたたみます。プレビューコメントは 1 件だけ投稿され、最初に変更箇所、次に完全なプレビューへのリンクを含むため、レビュアーは影響を受けたコンテンツを直接確認できます。

Dev container

assets/devcontainer.json を .devcontainer/devcontainer.json にコピーします。プロジェクトに paper/ がある場合は、image を -tex バリアント（ghcr.io/allenai/asta:latest-tex、またはバージョンを固定している場合は <version>-tex）に変更し、PR プレビューと同じ TeX パッケージで LaTeX Workshop がビルドするようにします。-tex イメージは、dev container のメタデータを通じて LaTeX Workshop 拡張機能を追加するため、devcontainer.json に記載する必要はありません。1 つのイメージで複数の論文に対応できます。次に、ユーザーの目的に合った方法を選びます。

• ローカルコンテナー（インストールせずに自分のマシンで作業する場合）：make dev を実行し、ローカルコンテナーに接続した状態で VS Code を開きます。
• Codespaces（どこからでもブラウザー経由でアクセスする場合）：変更をコミットし、GitHub リモートにプッシュします（必要に応じてリモートを作成します）。次に gh codespace create を実行し、ユーザーに URL を伝えます。Codespace のターミナルで asta auth login を使って認証するか（再ビルド後も保持されます）、任意の ASTA_TOKEN Codespaces シークレットを使用します。ポート 4848 で通知（onAutoForward: notify）が表示され、転送されたプレビュー URL が接続時のターミナルに出力されます。どちらかのリンクを別のブラウザータブで開きます。Simple Browser の localhost:4848 からは、ブラウザーベースの Codespace の転送ポートにアクセスできません。また、プライベートな転送 URL は埋め込みフレーム内で開けない場合があります。ローカルの VS Code では、Ports → Preview in Editor を使用できます。