dagger-design-proposals

Dagger の設計提案

Dagger の機能に関する設計提案を作成するためのガイドラインです。

作成前に

必ず最初に調査してください。

1. コンテキストを把握するため、internal-docs/dagger-codegen.md などの関連する内部ドキュメントを確認します
2. Dagger のコードベースで関連するコードを確認します。
   • GraphQL スキーマ：core/schema/*.go
   • CLI コマンド：cmd/dagger/*.go
   • コア型：core/*.go
3. パブリック API またはワークスペースの提案では、internal-docs/version-gating.md を読みます
4. 新しいパターンを提案する前に、既存のパターンを把握します

構成

# Part N: Title

*Builds on [Part N-1: Title](link)*

## Table of Contents
- [Problem](#problem)
- [Solution](#solution)
- [Core Concept](#core-concept)
- [CLI](#cli)
- [Status](#status)

## Problem

Numbered, concise limitations:

1. **Short title** - One sentence explanation.
2. **Short title** - One sentence explanation.

## Solution

One paragraph summary.

## Core Concept

GraphQL type definitions with inline docstrings:

```graphql
"""
Type description here.
"""
type Example {
  """Method description."""
  method(arg: String!): Result!
}
```

Go for implementation examples:

```go
func New(ws dagger.Workspace) *Example {
    // ...
}
```

## CLI

Real command examples:

```bash
$ dagger command --flag
OUTPUT
```

## Status

One line.

---

- Previous: [Part N-1](link)
- Next: [Part N+1](link) or "Part N+1: Title (coming soon)"

スタイル

• 簡潔に - 読者を信頼しましょう。冗長な部分は削除します。
• 表 - 比較には表を使います。
• API には GraphQL - Go のインターフェースではなく、型定義を使います。
• 実装には Go - モジュールで API を使用する方法を示す例を使います。
• 実例 - 抽象的な Foo/Bar ではなく、go-toolchain や node-toolchain を使います。
• 少ないほどよい - 指摘を受けたらセクションを削除します。

避けること

• 「Methods」セクションを分けること（GraphQL の docstring を使います）
• 特に価値がある場合を除き、「Design Rationale」セクションを設けること
• 実際のブロッカーではない「Open Questions」
• 型定義に Go を使うこと（GraphQL を使います）
• 誤解を招く可能性のあるレイアウト例
• 説明しすぎること

プロセス

1. Gist を信頼できる情報源にする - 早い段階で公開し、Gist で反復します
2. 各パートをリンクでつなぐ - 最下部に Previous/Next、最上部に「Builds on」を置きます
3. 各パートだけで完結させる - ただし、前のパートを踏まえた内容にします
4. すばやく反復する - ユーザーからのフィードバックを変更に反映します

ユーザーとの反復

確認したい質問やメモがある場合：

1. 最初に一覧を示す - 質問やメモをすべて、概要を示す番号付きリストにします
2. 一度に一つずつ - 各項目を個別に確認し、ユーザーの回答を待ちます
3. 一度にすべて出さない - 質問の詳細を一度にすべて提示してはいけません

コードベースの参照

提案を作成する際は、実際の Dagger のコードを参照します。

トピック	場所
GraphQL スキーマ定義	core/schema/*.go
CLI コマンド	cmd/dagger/*.go
コア型（Directory、File など）	core/*.go
エンジンの内部実装	engine/*.go
SDK コード生成	internal-docs/dagger-codegen.md、cmd/codegen/*.go
API バージョンゲート	internal-docs/version-gating.md、core/schema/*.go

例：Workspace.findUp を提案する前に、Host.findUp の仕組みを理解するには：

# Find the schema definition
grep -r "findUp" core/schema/host.go

# Find the implementation
grep -r "FindUp" core/host.go

公開

# Create new gist
gh gist create file.md --desc "Dagger Design: Part N - Title" --public

# Update existing gist
gh gist edit GIST_ID file.md

# Post changelog comment (always do this after updates)
gh api --method POST /gists/GIST_ID/comments -f body="## Changelog
- Change 1
- Change 2"

重要な変更を加えて Gist を更新した後は、必ず変更履歴のコメントを投稿してください。

関連するスキル

調査に役立つほかの Dagger スキルがないか確認します。

• engine-debugging - エンジンのデバッグワークフロー、トレースの調査、キャッシュのスナップショット
• internal-docs/dagger-codegen.md - SDK コード生成、テンプレート、バインディング
• internal-docs/version-gating.md - スキーマビューとパブリック API のバージョンゲート
• internal-docs/ - キャッシュとエンジン実装に関するリファレンス