fieldsmith 0.1.0 → 0.2.0

package/README.md

@@ -32,6 +32,7 @@ fieldsmith plan -f requirements.md -o bookshelf.json
 | コマンド | kintone | Claude |
 |---|---|---|
 | `deploy` `status` | 触る | **呼ばない** |
+| `check` | **触らない** | 呼ばない |
 | `plan` | 触らない | 呼ぶ |
 | `create` | 触る | 呼ぶ（= `plan` + `deploy`） |
 
@@ -57,6 +58,38 @@ fieldsmith plan -f requirements.md -o bookshelf.json
 これは「テンプレートから量産する」用途に向く。
 既存アプリに変更を反映したい場合は `update` を使う。
 
+## 先達について
+
+このツールの発想は、**[ginue](https://github.com/goqoo-on-kintone/ginue)**（[goqoo-on-kintone](https://github.com/goqoo-on-kintone)、MIT）に多くを負っている。
+
+ginue は kintone のアプリ設定を JSON として取り出し、Git のワークフローで扱う CLI。
+fieldsmith が受け継いだのは、道具立てそのものと言っていい。
+
+| | ginue | fieldsmith |
+|---|---|---|
+| 設定を取り出す | `pull` | `pull` |
+| 動作テスト環境へ反映 | `push` | `update` |
+| 運用環境へ反映 | `deploy` | `update --deploy` |
+| 送信前に確認 | `--dry-run` | `--dry-run` |
+
+**「アプリ設定はファイルにして版管理できる」「動作テスト環境で止めて人が確認してから本番へ出す」**
+という考え方は、ginue が先に示したものをそのまま踏襲している。
+fieldsmith の `update` が既定で運用環境に出ないのも、この 2 段階を守るためで、
+ginue の `push` と `deploy` の分け方に倣った。
+
+違いは抽象度にある。ginue は kintone の設定 JSON をそのまま扱い、
+多くの設定を高い忠実度で往復させる。fieldsmith は `AppSpec` という一段抽象化した形を挟み、
+表現できる範囲を狭める代わりに、人にも LLM にも書きやすくしている。
+テーブルやルックアップを扱えないのはそのためで、**忠実に環境を移したいなら ginue のほうが適している。**
+
+## サンプル
+
+そのまま `deploy` できる AppSpec の実例が [examples/](examples/) にある。
+
+```bash
+npx fieldsmith deploy examples/案件管理.json --dry-run
+```
+
 ## お試し手順
 
 全機能を一通り動かす手順書がある。副作用の小さい順（接続なし → kintone → Claude API）に
@@ -100,6 +133,9 @@ npm run fieldsmith -- create -f requirements.md
 | `revise <appId> [指示]` | 指示に沿って書き換えた AppSpec を作る（要 Claude API）|
 | `status <appId>` | 運用環境への反映状況を確認する |
 | `login` / `logout` | kintone の OAuth トークンの取得・破棄 |
+| `link <file.json>` | アプリ間の結線（ルックアップ・関連レコード一覧）を反映する |
+| `layout <appId>` | フォームの構造を表示する（読み取りのみ）|
+| `check <spec.json> <data.csv>` | 投入するデータが AppSpec に収まるか確かめる（接続しない）|
 | `schema` | AppSpec の書き方を出力する（AI エージェント向け）|
 | `plan [prompt]` | 要件から AppSpec を生成する。`-o` で保存 |
 | `create [prompt]` | 生成 → 確認 → デプロイ |
@@ -118,7 +154,7 @@ cp .env.example .env   # 値を埋める
 
 | 用途 | 設定するもの |
 |---|---|
-| `deploy` `pull` `diff` `update` `status` | kintone の認証情報（下記） |
+| `deploy` `pull` `diff` `update` `status` `layout` | kintone の認証情報（下記） |
 | `plan` `create` `revise` | 上記 + `ANTHROPIC_API_KEY` または `ant auth login` |
 
 ### kintone の認証は 2 通りから選ぶ
@@ -154,6 +190,22 @@ KINTONE_OAUTH_TOKEN_ENDPOINT=...
 両方あるときはパスワード認証を使う。`KINTONE_AUTH=oauth` で明示的に選べる。
 いま何で繋いでいるかは `--verbose` で分かる。
 
+#### どこに置くか
+
+次の順で探し、**最初に見つかった 1 つだけ**を読む。重ねて読むと、どの値が
+どこから来たのか追えなくなるため。
+
+| 順 | 場所 | 使いどころ |
+|---|---|---|
+| 1 | `$FIELDSMITH_ENV` | どれを読むかを完全に決めたいとき |
+| 2 | `./.env` | リポジトリ直下で作業しているとき |
+| 3 | `~/.config/fieldsmith/default.env` | **どのディレクトリから叩いても効かせたいとき** |
+
+3 番目があると、案件のディレクトリから `fieldsmith deploy spec.json` がそのまま通る。
+どのファイルを読んだかは `--verbose` で出る。
+
+既にある環境変数は上書きしない。CI で注入した値のほうが優先される。
+
 いずれの場合も、実行するユーザーに **「アプリの作成」権限**が必要。
 
 ### kintone 側の準備
@@ -219,6 +271,310 @@ npm run fieldsmith -- login
   **kintone に 1 リクエストも投げる前に**理由付きで弾く。
 - 一覧や `titleFieldCode` から参照するフィールドコードの存在も、事前に検証する。
 
+### ルックアップを対象外にしている理由
+
+`LOOKUP` と `REFERENCE_TABLE` を「v1 では未対応」としているのは、
+**この 2 つが他のアプリに依存する**ため。
+
+グループとテーブルも当初は同じ並びだったが、どちらもアプリ内で完結する構造物なので、
+[`layout: "sections"`](#グループフィールド-sections) と [`table`](#テーブル) で対応した。
+ルックアップと関連レコード一覧は、そこが違う。
+
+**1. AppSpec を環境非依存に保つため（主たる理由）**
+
+ルックアップの設定には**相手アプリの指定**が要る。これを spec に書くと、その AppSpec は
+特定の kintone 環境に縛られる。`space` を `examples/` の spec に持たせていないのと
+同じ理由で、「同じ spec を別の環境・別のスペースにもう 1 つ」ができなくなるのは困る。
+
+> 逃げ道が無いわけではない。`relatedApp` はアプリ ID (`app`) のほかに
+> **アプリコード** (`code`) でも書けて、両方指定すると `code` が勝つ。
+> ただしそれは「相手アプリがどの環境でも同じアプリコードで存在している」ことが前提で、
+> fieldsmith はその前提を**作ることも確かめることもできない**。
+
+アプリ間の参照は **AppSpec の外に置き、kintone 上で人が繋ぐ**という前提にしている。
+`examples/` がその形になっている。
+
+| ファイル | どう扱っているか |
+|---|---|
+| `本棚.json` | 「蔵書アプリはこのアプリの棚 ID をキーにルックアップで引く」と `description` に**文章で**書く |
+| `蔵書.json` / `蔵書管理.json` | `本棚ID` を**ただの文字列フィールド**として持つ |
+
+**2. `deploy` の決定性が保てないため**
+
+`deploy` は「AppSpec 1 つ → 新しいアプリ 1 つ」を毎回同じ結果で作る操作。ルックアップを
+認めると、相手アプリが先に存在している必要があり、アプリ間の依存解決と作成順序という
+別の問題が入り込む。
+
+さらに `--dry-run` は kintone に接続しないので、**相手アプリやキーフィールドの存在を
+検証できない**。「検証は通ったのにデプロイの途中で落ちる」型の失敗が増える。
+
+### 関連レコード一覧を対象外にしている理由
+
+`REFERENCE_TABLE` には、ルックアップと重なる理由と、この型だけの事情がある。
+
+**1. 相手アプリに依存する（ルックアップと共通）**
+
+`referenceTable` にも参照先アプリの指定が要る。上のアプリコードの話もそのまま当てはまる。
+
+**2. `--dry-run` が意味を成さない**
+
+`condition.relatedField` と `displayFields` は、**相手アプリの**フィールドコード。
+どちらも `referenceTable` を書くなら必須。`--dry-run` は kintone に接続しないので、
+これらが実在するかを確かめられない。
+
+fieldsmith の検証は「**kintone に 1 リクエストも投げる前に**弾く」ことを拠り所にしている。
+確かめようのない項目を通すと、その拠り所が崩れる。
+
+**3. データを持たないので、外すコストが低い（この型だけの事情）**
+
+関連レコード一覧は**表示だけの装置**で、レコードに値を持たない。
+
+> 関連レコード一覧 | REFERENCE_TABLE | 値の取得はできません。
+> 関連レコード一覧 | REFERENCE_TABLE | 値の登録または更新はできません。
+>
+> — [フィールド形式](https://cybozu.dev/ja/kintone/docs/overview/field-types/)
+
+だから AppSpec から外しても、**レコードのデータは 1 件も失われない**。デプロイした後に
+kintone の画面で足しても、既にあるレコードには何の影響もない。
+
+値を持つルックアップとは、ここが違う。ルックアップの実体は `SINGLE_LINE_TEXT` /
+`NUMBER` / `LINK` に設定を付けたもので、フィールドそのものにはデータが入っている。
+
+### `pull` はどちらも黙って捨てない
+
+| | `pull` の扱い |
+|---|---|
+| 関連レコード一覧 | フィールドごと落として警告に出す（値を持たないので失われるデータは無い）|
+| ルックアップ | **フィールドは残し**、ルックアップ設定を落としたことを警告に出す |
+
+ルックアップを残すのは、そこに**データが入っているから**。落とすと `update` で
+削除候補に送られてしまう。残った形は `examples/蔵書.json` と同じ「`本棚ID` を
+ただの文字列フィールドとして持つ」状態になる。
+
+その spec を `update` で送り返しても、kintone 側のルックアップ設定は消えない。
+フィールド設定変更 API は「[省略したパラメーターの設定は変更されません](https://cybozu.dev/ja/kintone/docs/rest-api/apps/form/update-form-fields/)」ため。
+
+## テーブル
+
+同じ `table` を書いたフィールドが、kintone のテーブルの列になる。
+
+```jsonc
+{
+  "fields": [
+    { "type": "SINGLE_LINE_TEXT", "label": "件名" },
+    { "type": "SINGLE_LINE_TEXT", "label": "品名", "table": "明細" },
+    { "type": "NUMBER",           "label": "単価", "table": "明細", "unit": "円" },
+    { "type": "NUMBER",           "label": "数量", "table": "明細" }
+  ]
+}
+```
+
+```
+件名
+▦ 明細 (テーブル)
+    品名 | 単価 | 数量
+```
+
+**入れ子では書かない。** `group` がセクションを決めるのと同じく、フィールドに付けた印が
+テーブルを決める。こうしている理由は 2 つある。
+
+- AppSpec が平らなままなら、差分・検証・一覧の扱いが今までと変わらない
+- `plan` の構造化出力はプロパティ数の上限が厳しく、入れ子を足す余裕が無い
+
+### 決まり
+
+- **同じ `table` は続けて並べる。** 離れていると 2 つのテーブルに割れるので検証で弾く
+- `table` と `group` は**同時に指定できない**。kintone はテーブルの中にグループを置けない
+- `table` の名前がテーブルのフィールドコードになる。フィールドコードと重ならない名前にする
+- テーブルの列は**一覧 (`views`) に指定できない**。1 レコードに複数の値を持つため
+
+### `update` はテーブルを変更しない
+
+`deploy` はテーブルを作れるが、**`update` は既存のテーブルに触れない。**
+列を足す・外す・出し入れしようとすると、1 リクエストも投げずに終了コード 2 で止まる。
+
+```
+  ! 数量: テーブル「明細」の列を追加 (update では反映できない)
+```
+
+kintone のテーブルには**列の退避先が無い**。グループは `layout` に行を入れ子で持てるが、
+テーブルは `fields` の平らな配列で、行も入れ子も持てない。
+
+```
+GROUP    → "layout": [ ROW, ROW, ... ]
+SUBTABLE → "fields": [ field, field ]
+```
+
+列を外へ出すのは親を変えることで、kintone では作り直しになり**データが失われる**。
+fieldsmith の「消さずに削除候補へ移す」が成り立たないので、中途半端に適用せず止める。
+
+テーブルを変えたいときは kintone の画面で変更し、そのあと `pull` で spec を取り直す。
+
+`plan` / `create` / `revise` はテーブルを作らない（構造化出力の上限のため）。
+`revise` にかけても、元の spec のテーブルは**列の所属ごと引き継ぐ**。
+
+## アプリ間の結線
+
+ルックアップと関連レコード一覧は AppSpec に入れていない（[理由](#ルックアップを対象外にしている理由)）。
+かと言って手で繋ぐしかないのも困るので、**環境に依存する部分だけを別のファイルに閉じ込める**。
+
+```jsonc
+{
+  "links": [
+    {
+      "type": "LOOKUP",
+      "app": "蔵書",                  // 文字列 = アプリコード / 数値 = アプリ ID
+      "code": "本棚ID",               // ← AppSpec が作ったフィールド
+      "relatedApp": "本棚",
+      "relatedKeyField": "棚ID",
+      "fieldMappings": [{ "field": "棚名", "relatedField": "棚名" }]
+    },
+    {
+      "type": "REFERENCE_TABLE",
+      "app": "蔵書",
+      "code": "同じ棚の本",            // ← link が作るフィールド
+      "label": "同じ棚の本",
+      "relatedApp": "本棚",
+      "condition": { "field": "本棚ID", "relatedField": "棚ID" },
+      "displayFields": ["棚ID", "棚名"],
+      "placeAfter": "本棚ID"
+    }
+  ]
+}
+```
+
+```bash
+fieldsmith link links.json --dry-run    # 何が起きるか（kintone を変更しない）
+fieldsmith link links.json              # 動作テスト環境まで
+fieldsmith link links.json --deploy     # 運用環境へ
+```
+
+### ファイルは環境に依存しない
+
+**アプリを文字列で書くとアプリコードとして解決する。** 数値ならアプリ ID。
+アプリコードで書いておけば、**同じファイルが開発環境でも本番でも効く**。
+接続先は他のコマンドと同じく `.env` から来るので、ファイルには書かない。
+
+### 作るものと作らないもの
+
+| | フィールドを作るのは | なぜ |
+|---|---|---|
+| `LOOKUP` | **AppSpec** | 実体は `SINGLE_LINE_TEXT` / `NUMBER` / `LINK` で、**値が入る**。データを持つものは AppSpec が持つ |
+| `REFERENCE_TABLE` | **link** | 値を持たない。AppSpec に無くても失われるデータが無い |
+
+ルックアップにするフィールドが AppSpec に無ければ、`link` はそう言って止まる。
+
+> 既にデータが入っているフィールドにも後から結線できる。実機で確かめてある
+> （値は消えず、コピーは編集画面で取得したときだけ走る）。
+
+### 送るのは書いた項目だけ
+
+**kintone は書かなかった項目を勝手に埋める。** `sort` に `レコード番号 desc`、
+`size` に `5` が入る。これを差分とみなすと、中身が同じなのに毎回「変わった」と
+言い続けることになるので、**書いた項目だけを比べる**。AppSpec の
+「書かれていない項目は現状維持」と同じ扱い。
+
+だから何度流しても結果は同じになる。
+
+### `--dry-run` は読み取りに接続する
+
+`deploy --dry-run` は kintone に一切繋がないが、`link --dry-run` は**読み取りだけ繋ぐ**。
+相手アプリのフィールドが実在するかは、繋がないと確かめようがないため。
+
+送る前に見るもの。
+
+| | どこを読む |
+|---|---|
+| `app` / `relatedApp` が解決できるか | アプリ一覧 |
+| `condition.field` `fieldMappings[].field` `placeAfter` | そのアプリのフォーム |
+| `condition.relatedField` `displayFields` `lookupPickerFields` | **相手アプリ**のフォーム |
+| ルックアップの対象が `SINGLE_LINE_TEXT` / `NUMBER` / `LINK` か | そのアプリのフォーム |
+| キーに**重複禁止**が設定されているか | 相手アプリのフォーム |
+
+最後のは kintone の決まりで、ここで弾かないと反映の途中で落ちる。
+
+### 消さない
+
+ファイルに無い結線が kintone 側にあっても**削除しない**。警告で知らせるだけ。
+フィールドを消さない方針と揃えている。
+
+## フォームの構造を読む
+
+`pull` は AppSpec を吐くので、**どれが同じ行に並んでいるか**が見えない。
+「このフィールドの近くに何かを置きたい」ときに要るのは、定義ではなく並び。
+
+```bash
+fieldsmith layout 772
+```
+
+```
+アプリ 772「在庫明細」 5 行
+
+1: 年月日 (DATE) | 倉庫コード (SINGLE_LINE_TEXT) | 倉庫名 (SINGLE_LINE_TEXT)
+2: 倉庫情報 (REFERENCE_TABLE) → アプリ 774
+3: <LABEL>
+4: ▦ 明細 (テーブル)
+     品名 (SINGLE_LINE_TEXT) | 数量 (NUMBER)
+5: ▼ _削除候補 (グループ)
+     入数 (NUMBER)
+```
+
+**AppSpec が扱えないものこそ、見えることに価値がある。** 関連レコード一覧は
+参照先のアプリを併記し、ラベルや罫線も `<LABEL>` として出す。
+`_削除候補` の中身が見えると、型を変えた名残にも気づける。
+
+既定は運用環境。`--preview` を付けると動作テスト環境を見る（反映後の答え合わせに要る）。
+
+## 投入するデータを先に確かめる
+
+`deploy --dry-run` が「その spec は正しいか」を接続せずに見るのに対して、
+`check` は「**そのデータはこの spec に入るか**」を見る。
+
+```bash
+fieldsmith check 取引先マスタ.json records.csv
+```
+
+```
+3,927 件 / 63 列 を 取引先マスタ.json と突き合わせます
+
+✗ 締日: maxValue 31 を超える値があります (260 件)
+    3421 行目 (取引先コード=51234001001) = "90"
+    3428 行目 (取引先コード=51234002001) = "90"
+✗ 郵便番号: maxLength 8 を超える値があります (最長 9 文字) (5 件)
+    1122 行目 (取引先コード=51234099001) = "x305-0056"
+⚠ メールアドレス: spec にありますが CSV に列がありません (空で登録されます)
+⚠ 与信限度額: CSV にありますが spec にありません (無視されます)
+
+2 件のエラー / 2 件の警告
+```
+
+**kintone のレコード追加は 100 件のかたまり単位で失敗する。** 1 件の違反で
+そのかたまりが丸ごと落ちるので、6 件の不正データが 600 件の取りこぼしになる。
+投入してから気づくと被害が桁で増えるため、先に突き合わせる。
+
+`deploy` の前に流すと、型や制約の決め方にも跳ね返る
+（「締日」に `maxValue 31` を付けてよいのか、そもそも数値なのか）。
+
+### 見るもの
+
+| | 内容 |
+|---|---|
+| 必須 | `required` の列が空 |
+| 重複 | `unique` の列に同じ値 |
+| 選択肢 | `options` にない値 |
+| 数値 | 数値として読めない / `minValue` `maxValue` の外 |
+| 文字数 | `minLength` `maxLength` の外 |
+| 日付 | `DATE` `TIME` `DATETIME` として読めない |
+| 列の過不足 | spec にあって CSV に無い、その逆 |
+
+CSV は **cli-kintone と同じ形式**を読む。見出しはフィールドコード、複数値は
+セル内の改行区切り、テーブルは `*` 列でレコードの先頭行を示す。
+同じファイルをそのまま `cli-kintone record import` に渡せる。
+
+- kintone にも Claude にも接続しない。認証情報が要らない
+- 違反があれば終了コード 2。`--json` で `issues[]` を機械可読に出す
+- 判定に迷う値は通す。**取りこぼすより誤検出のほうが困る**ため
+
 ## スペースへの配置
 
 アプリを特定のスペースに作れる。CLI の `--space` が AppSpec の `space` より優先される。
@@ -258,10 +614,37 @@ kintone がスレッドの指定を求めた場合は `--thread` を使う。ス
 {
   "layout": "grouped",                          // 既定。省略してもこの動作
   "layout": { "mode": "grouped", "maxPerRow": 2 }, // 1 行あたりの上限を変える (既定 3)
+  "layout": "sections",                         // group をグループフィールドにする
   "layout": "stacked"                           // レイアウトに触らない (1 行 1 フィールド)
 }
 ```
 
+### グループフィールド (`sections`)
+
+`grouped` の `group` は横並びのヒントで、kintone 上には現れない。
+`sections` にすると、同じ `group` のフィールドが **kintone のグループフィールド**に入る。
+
+```jsonc
+{
+  "layout": "sections",
+  "fields": [
+    { "type": "SINGLE_LINE_TEXT", "label": "書名",   "group": "書誌情報" },
+    { "type": "SINGLE_LINE_TEXT", "label": "著者",   "group": "書誌情報" },
+    { "type": "DATE",             "label": "貸出日", "group": "貸出" }
+  ]
+}
+```
+
+書き方は `grouped` と同じ。`group` の付いていないフィールドは、これまで通り素の行になる。
+
+- **`group` の名前がグループのフィールドコードになる。** ラベルからコードを導くのと
+  同じ規則を使うので、同じ名前からは毎回同じコードが出る。更新を繰り返しても
+  グループは増えない
+- そのためフィールドコードと重なる名前は使えない（検証で弾かれる）
+- グループは開いた状態で作られる（畳んだ状態にするのは `_削除候補` だけ）
+- **AppSpec から消えたグループは、空のまま残る。** フィールドを削除しないのと同じ理由で、
+  グループも消さない。不要なら kintone の画面で削除する（`update` が警告で知らせる）
+
 ### 並べ方の規則
 
 **並び順は変えない。** AppSpec に書いた順序のまま、隣り合った同じ系統のフィールドを
@@ -344,7 +727,7 @@ memo
 
 1. 動作テスト環境にアプリを作成
 2. フィールドを追加（100 件ずつ分割）
-3. フォームの並びを整える（`layout` が `grouped` の場合のみ。既定で有効）
+3. フォームの並びを整える（`layout` が `grouped` / `sections` の場合のみ。既定で有効）
 4. アイコン画像を生成してアップロード（`icon` の指定がある場合のみ）
 5. 一般設定を変更（アイコンまたは他の設定がある場合のみ）
 6. 一覧を変更（指定がある場合のみ）
@@ -386,11 +769,42 @@ AppSpec は kintone の設定をすべて表現できるわけではない。落
 現状で落ちるもの: テーブル・ルックアップ・関連レコード一覧などの未対応フィールド型、
 カスタマイズ一覧、アプリアイコンの画像、細かなレイアウト。
 
+### アイコンは往復する
+
+kintone はアプリアイコンを**画像**として持つので、画像そのものからは
+「🏢 を描いた」ことも「背景色に何を使った」ことも読み取れない。
+
+そこで**アップロードするファイル名に書いておく**。
+
+```
+fieldsmith-icon-🏢-2563eb.png
+```
+
+`getAppSettings` はこのファイル名を返すので、`pull` が `icon` と `iconBackground` に
+戻せる。だから `pull` → 絵文字を書き換える → `update` でアイコンを変えられる。
+
+人が kintone の画面で差し替えた画像はこの形にならない。その場合は従来どおり
+「AppSpec には含められません」と警告する。
+
+> アイコンは**変わったときだけ**上げ直す。毎回上げると、更新のたびに
+> 画像ファイルが増えていく。
+
 ### レイアウトについて
 
-`pull` は `"layout": "stacked"` を付けて返す。AppSpec は任意のレイアウトを
-表現できないので、**既存の並びに手を触れない**という指定にしてある。
-横並びにしたい場合は `"layout": "grouped"` に書き換える。
+`pull` は**読み取れたものだけを名乗る**。
+
+| フォームの状態 | `pull` が返す `layout` |
+|---|---|
+| グループフィールドがある | `"sections"`（`group` に所属も復元する）|
+| それ以外 | `"stacked"`（既存の並びに手を触れない）|
+
+横並びは読み取れない。1 行に 3 つ並んでいても、fieldsmith が並べたのか人が画面で
+並べたのか区別が付かないので、`stacked` と言う。横に並べたい場合は
+`"layout": "grouped"` に書き換える。
+
+グループは読み取れる。レイアウトに `GROUP` があれば、それは疑いようもなくセクションなので、
+`sections` と名乗って往復できるようにしてある。**`pull` した spec をそのまま `update` しても
+レイアウトは書き換わらない**（両方が同じ指定・同じ並びなので差分が出ない）。
 
 フィールドの順序は、フォームのレイアウト上の位置から復元する
 （`getFormFields` はオブジェクトを返すので順序が保証されない）。
@@ -424,15 +838,42 @@ fieldsmith diff 761 target.json
 **順序が原因で追加や削除候補になることはない。** 対応付けはフィールドコードで行うので、
 並べ替えただけなら誤判定しない。
 
-ただし**並べ替えそのものは差分として拾う**（`layout` が `grouped` のとき）。
+ただし**並べ替えそのものは差分として拾う**（`layout` が `grouped` / `sections` のとき）。
 
 ```
   ~ フォームの並びを組み直す (並び順)
 ```
 
-`layout` が `stacked`（`pull` の既定）の場合は「既存の並びに手を触れない」指定なので、
+`layout` が `stacked` の場合は「既存の並びに手を触れない」指定なので、
 並べ替えても何も起きない。差分にも出さない。並びを変えたいときは `"layout": "grouped"` にする。
 
+`sections` では、フィールドが増減したときも組み直す。レイアウトを書かないと、
+足したフィールドが kintone によってフォーム末尾に置かれ、**所属するはずのグループの外**に
+出てしまうため。
+
+```
+  ~ フォームの並びを組み直す (フィールドの増減)
+```
+
+### AppSpec に現れないものは、レイアウト上で保たれる
+
+フォームには AppSpec が扱わないものが載っている。
+
+| | AppSpec | レイアウト |
+|---|---|---|
+| 関連レコード一覧・ルックアップ設定 | 表現しない | 載っている |
+| ラベル・スペース・罫線 | 表現しない | 載っている（`code` ではなく `elementId` を持つ）|
+
+`update` が並びを組み直すのは AppSpec に書かれたフィールドだけで、**それ以外は
+直前のフィールドの位置に戻す**。組み直しは AppSpec を起点にするので、
+何もしないと消えてしまうため。
+
+フィールドを落とすとレイアウト変更 API が「指定が足りない」で失敗し、
+飾りは API が求めないぶん黙って消える。どちらも起こさない。
+
+> 手掛かりにしていたフィールドごと削除候補へ移った場合だけ、位置を保てずに末尾へ回る。
+> それでも捨てはしない。
+
 ### 同一性はフィールドコードで決まる
 
 ラベルだけ変えたなら「同じフィールドの変更」、コードが変わったら「別フィールドの追加 + 元は削除候補」。
@@ -505,6 +946,35 @@ kintone の設定変更 API は、**省略した項目を変更しない**。fie
 差分にも出さない。出すと「実際には何も起きないのに差分が永遠に消えない」ことになる。
 値を変えたいときは明示的に書く。
 
+#### キーを消しても、制約は外れない
+
+ここがいちばんハマる。**キーを消す＝制約を外す**と読みたくなるが、そうはならない。
+
+```jsonc
+// 現状: maxValue 31 が設定されている
+{ "type": "NUMBER", "code": "締日", "minValue": 0 }                    // → 31 のまま
+{ "type": "NUMBER", "code": "締日", "minValue": 0, "maxValue": "" }    // → 外れる
+```
+
+**外すときは空文字を書く。** kintone は未設定の上限・下限・初期値を空文字で表すので、
+空文字がそのまま「制限なし」を意味する。真偽値なら `false` を書く。
+
+黙って据え置くと「差分なし＝変わっていない」と読めてしまうので、
+`diff` と `update` が**外し方つきで知らせる**。
+
+```
+注意:
+  ⚠ 締日: maxValue を spec から外しましたが、kintone 側の "31" は据え置かれます
+    (外すには "maxValue": "" と書きます)。
+```
+
+外し方を示せるものだけが対象。`theme` のように「空にする」書き方が無いものは黙って見送る。
+
+#### 数値は文字列でも数値でも書ける
+
+kintone は上限・下限・初期値を**文字列で返す**（`"31"`）。spec にはどちらでも書けて、
+`0` と `"0"` は同じものとして扱う。書き方の違いが差分に出ることはない。
+
 ### 何度流しても同じ結果になる
 
 `update` は運用環境ではなく**動作テスト環境**を読んで差分を取る。
@@ -565,6 +1035,23 @@ fieldsmith revise 761 "受注確度を S/A/B/C の4段階にして、失注理
 
 ## AI エージェントから使う
 
+Claude Code から使う場合の設定と注意点は **[docs/claude-code.md](docs/claude-code.md)** にまとめてある
+（`CLAUDE.md` と `.claude/settings.json` の雛形つき）。
+
+手順そのものをエージェントに持たせるなら **[skills/kintone-appspec](skills/kintone-appspec)** を使う。
+新規作成（`deploy`）と既存アプリの更新（`pull` → `diff` → `update`）の進め方、確認を取る
+タイミング、よくある失敗の直し方が入っている。fieldsmith 自体のインストールは不要
+（`npx -y fieldsmith` に落ちる）。
+
+このリポジトリは Claude Code のプラグイン marketplace を兼ねているので、2 コマンドで入る。
+
+```bash
+claude plugin marketplace add motohasystem/fieldsmith
+claude plugin install kintone-fieldsmith@fieldsmith
+```
+
+ファイルをコピーして使ってもよい。詳細は [skills/README.md](skills/README.md)。
+
 エージェントの仕事は **AppSpec を書くこと**で、デプロイはシェルコマンド 1 つ。
 そのために必要なものは揃えてある。
 
@@ -841,3 +1328,8 @@ MIT License（[LICENSE](LICENSE)）
 
 同梱している日本語フォント **DotGothic16** は SIL Open Font License 1.1 です。
 ライセンス全文は [assets/fonts/OFL.txt](assets/fonts/OFL.txt) に同梱しています。
+
+## 謝辞
+
+設計の下敷きにさせてもらった [ginue](https://github.com/goqoo-on-kintone/ginue) の作者と
+メンテナの方々に感謝します。詳しくは [先達について](#先達について)。