依頼一覧をCSVとJSONの両方で作り、読み方の違いを見比べる

原稿の管理表（13項目：記事ID・カテゴリ・要件ID・先に読むと理解しやすい記事・成果物パス・対象ツール・検証状況・最終更新日など）

管理項目	内容
記事ID	00-02
主な中カテゴリ	00-02 ファイル・コード・データを区別する
関連中カテゴリ	00-01、06-01
関連要件ID	REQ-001
先に読むと理解しやすい記事	00-01（アプリが動く仕組みをつかむ）を読んでいると理解しやすい。未読でも本文で必要な内容は説明する
到達目標	ファイルとフォルダ、OS、実行環境、プログラムと入力データ、CSV・JSONなどのデータ形式の違いを、目の前のファイルを指して説明できる
3層の配置	理解する＝第3〜4節／作って確かめる＝第5〜7節／設計を判断する＝第8節
成果物パス	templates/00-02-file-structure_template.md、templates/00-02-file-structure_example.md、examples/00-02-file-structure/（count_by_state.js、requests.csv、requests.json、requests-comma.csv）、evidence_public/phase5b2a-2026-09-20/00-02/run_log.md
出典	第11節参照
対象ツール・バージョン	教材演習用にNode.js v24.18.0（node:fs・node:path のみ使用。読み込みと表示だけで、特定ツールの知識は要らない）
検証状況	本文・ひな形・記入例はClaude Codeが作成。第5.4節の最小例は examples/00-02-file-structure/ を正本とし、2026-09-20にローカルで実行して stdout・stderr・終了コードを記録済み（第6〜7節、evidence_public/phase5b2a-2026-09-20/00-02/run_log.md）。人による実読・内容確認は未実施
残課題	第11節参照
最終更新日	2026-09-20（新規作成。同日、Phase 5B-2A：読む順路・第4節の判断項目を追加。完了条件「プログラム・入力データ・出力の3つが別ファイルとして例示されている」を満たすため、実際のファイル3種と読み込みプログラムを examples/ に置き、実行して読み違え（カンマ）を観察した。用語説明・CSV/JSONの例・比較表は不変）

この記事の会社・人物・データはすべて架空の設定です。実在する会社や案件とは関係ありません。第5.4節の最小例は examples/00-02-file-structure/ の正本と同じもので、実行結果は2026-09-20にローカル環境で実際に実行して記録したものです（第6〜7節）。

この記事は何の話か。00-01で見た「保存先」の中身が、実際にはファイルやフォルダとしてどう整理されているかを、CSVとJSONという2つのデータ形式を例に見比べる話です。あわせて、「プログラム」「入力データ」「出力」が別のものであることを、実際のファイルを指して確かめます。

なぜ必要か。「プログラム」「入力データ」「出力」を区別できないと、どのファイルを直接触ってよくて、どのファイルはプログラムが自動で作るものなのかが分からず、大事なファイルを誤って書き換えてしまう危険があります。AIに「このデータを集計して」と頼むときも、どのファイルが入力で、何が出力かを人が指せなければ、AIは推測で選びます。

この記事を読むとできるようになること。

• ファイルとフォルダ、OS、実行環境、プログラムと入力データ、CSV・JSONの違いを、目の前のファイルを指して説明できる
• 架空の依頼一覧をCSVとJSONの両方で作り、同じプログラムで読んで同じ結果になること、区切り文字（カンマ）が混ざると読み違えることを見比べられる
• 依頼データの形式候補を、可読性・扱いやすさ・移行時の誤りやすさから比較できる

読む順路。この記事は3つの深さで読めます。全部を順に読む必要はありません。

• 基本だけ理解する：第1節→第2節（用語）→第3.1〜3.2節（見た目の違いと読み違え）→第5.2節（プログラム・入力・出力の区別）→第9節。コードを動かさなくても、目の前のファイルが「プログラム」「入力」「出力」のどれかを指せるようになります。
• 作って確かめる：上に加えて第4節（判断すること）→第5.3〜5.4節（CSV版・JSON版と最小のプログラム）→第6節（実際に読んだ結果と、カンマで列がずれる様子）→第7節。
• 設計判断を深める：上に加えて第8節（形式候補の比較と、05-01へ持ち越す論点）。

1. 今回の業務課題と完成するもの

この記事でやることは、架空の依頼一覧を、CSVとJSONという2つの代表的なデータ形式で小さく作り、同じプログラムで読んで見比べることです。

00-01では「保存先」という登場人物が出てきましたが、その中身が具体的にどんな形のファイルなのかはまだ扱っていません。この記事では、その具体的な形を扱います。

この記事を読み終えると、次のものが手元にできます。

• 基本用語の対応表（ファイル、フォルダ、OS、実行環境）
• 同じ依頼一覧をCSVとJSONで表した、架空データの小さな例と、それを読む最小のプログラム（examples/00-02-file-structure/）

2. 前提知識と読む順路

この記事で使う言葉を先に説明します。

ファイルとフォルダ

一言でいうと、ファイルは1つのまとまったデータや文書、フォルダはファイルを整理して入れる箱です。たとえば、「依頼一覧.csv」という1つのファイルを、「みらい業務サービス」というフォルダの中に入れて整理します。

これがないと、依頼のデータがどこにあるか分からなくなります。

OS（基本ソフトウェア）

一言でいうと、パソコンやサーバーが動くための土台になるソフトウェアです。たとえば、ファイルを開く・保存する・実行するといった基本的な操作は、OSが提供する仕組みの上で行われます。

これがないと、他のソフトウェア（プログラムや実行環境）がパソコンの部品（画面、記憶装置など）を直接使う方法が分からず、何も動きません。

実行環境

一言でいうと、プログラムを実際に動かすための、パソコン側の準備です（06-01でも扱います）。たとえば、依頼データを読み込むプログラムを動かすには、そのプログラムを解釈できる実行環境が必要です。

プログラムと入力データ

一言でいうと、プログラムは「何をするか」を書いたもの、入力データはプログラムが処理する対象です。たとえば、「依頼一覧を読んで、状態ごとに件数を数える」という指示がプログラムで、依頼一覧そのものが入力データです。

これがないと、プログラムを直接書き換えることと、扱うデータを書き換えることの違いが分からなくなり、意図せずプログラムを壊してしまうことがあります。

CSV・JSON

一言でいうと、どちらもデータを整理して保存するための形式です。CSVは表計算のように行と列でデータを並べる形式、JSONは項目名と値の組を入れ子にして表せる形式です。

これがないと、依頼一覧のようなデータを、人にもプログラムにも読める形で受け渡すことができません。

読む順路：登場人物の見取り図は00-01が該当します。この記事で見るファイル構成は、06-01（作業場所と実行環境を整える）の作業フォルダの土台になります。

3. 理解する：形式によって何が変わるか

3.1 CSVとJSONの見た目の違い

同じ依頼1件を、CSVとJSONで表すと次のようになります。

CSV（表形式、カンマで区切る）：

依頼ID,依頼者,件名,状態
REQ-0001,佐藤,会議室の予約,提出済み

JSON（項目名と値の組）：

{
  "依頼ID": "REQ-0001",
  "依頼者": "佐藤",
  "件名": "会議室の予約",
  "状態": "提出済み"
}

CSVは表計算ソフトで開くとそのまま表に見えるため人が読みやすく、JSONは項目名がデータと一緒に書かれているため、項目が多い・入れ子になったデータを表しやすいという違いがあります。

3.2 文字コード・日付表記で読み方が変わる例

これらは、この記事で扱う「読み違え」の代表例です。3つ目のカンマの例は、第6節で実際に起こして観察します。05-01・08-02で、実際にどう保存するかを決める際、この読み違えを防ぐ工夫（文字コードの統一、日付形式の統一など）を扱います。

3.3 よくある誤解

「保存されているファイルは何でも自由に書き換えてよい」。プログラムが自動で作る出力ファイルを人が手で書き換えると、次にプログラムが動いたときに内容が上書きされたり、想定外の形式になったりします。

「CSVとJSONはどちらが優れているというものがある」。優劣ではなく、扱うデータの形（単純な表か、入れ子になった構造か）によって向き不向きが変わります。

「文字化けは特別な場合にしか起きない」。文字コードの設定が違うだけで、日本語を含むデータでは頻繁に起こり得ます。

「AIに形式を選ばせればよい」。AIは形式ごとの一般的な特徴を提示できますが、この業務でどちらを使うかは、後工程（05-01・03-03）で人が判断します。

4. 判断すること

この記事は形式を「決める」記事ではありませんが、見比べるときに人が判断することが3つあります。

勝手に決めてはいけないこと：依頼データの保存形式（CSVかJSONか、あるいはデータベースか）はこの記事で確定しません。実在する業務データやファイルをこの記事の例に使いません。すべて架空のデータで説明します。

AIに任せる範囲：CSVとJSONの一般的な特徴の説明、読み込みプログラムの下書き、形式の変換はAIに任せられます。しかし、自分の業務のどのファイルが入力で何が出力かを指すこと、取り決め（文字コード・日付）をそろえること、形式を決めることは人が行います。

5. 作って確かめる：架空データの小さな例を作る

5.1 準備

00-01の見取り図（保存先という登場人物）と、06-01で確認するNode.jsの実行環境を確認します。この記事の最小例は、読み込んで表示するだけです。

5.2 プログラム・入力データ・出力を区別する例

3つは別のファイル・別のものです。入力データは人が用意し、書き換えてよいもの。プログラムは動かし方を書いたもので、書き換えると動きが変わるもの。出力は動かすと生まれるもので、手で直しても次に動かせば消えるものです。

5.3 架空の依頼一覧（CSV版とJSON版）

CSV版（requests.csv、文字コードUTF-8、日付はYYYY-MM-DD形式）：

依頼ID,依頼者,件名,状態,提出日
REQ-0001,佐藤,会議室の予約,提出済み,2026-09-18
REQ-0002,田中,備品の発注,承認済み,2026-09-15

JSON版（requests.json、同じ内容）：

[
  { "依頼ID": "REQ-0001", "依頼者": "佐藤", "件名": "会議室の予約", "状態": "提出済み", "提出日": "2026-09-18" },
  { "依頼ID": "REQ-0002", "依頼者": "田中", "件名": "備品の発注", "状態": "承認済み", "提出日": "2026-09-15" }
]

見比べて気づく点：

• CSVは1行が依頼1件に対応し、表計算ソフトでそのまま開ける。
• JSONは項目名が各件に繰り返し書かれるため、CSVよりファイルの見た目は大きくなるが、項目の意味を取り違えにくい。
• どちらも日付の形式（YYYY-MM-DD）を統一しておかないと、あとで日付として正しく扱えない可能性がある（第3.2節）。

5.4 最小のプログラム（読み込んで件数を数える）

2つの入力データを読み、状態ごとの件数を表示する最小のプログラムです（examples/00-02-file-structure/count_by_state.js）。ファイルを読むだけで、何も書き換えません。

// 教材演習用：依頼一覧（入力データ）を読み込み、状態ごとの件数（出力）を表示する最小のプログラム。
// 使い方: node count_by_state.js                    （requests.csv と requests.json の両方を読む）
//         node count_by_state.js requests-comma.csv  （件名にカンマを含む CSV を読み、読み違えを観察する）
// このプログラムはファイルを読むだけで、何も書き換えない。
const fs = require("node:fs");
const path = require("node:path");

function readCsv(file) {
  const lines = fs.readFileSync(path.resolve(__dirname, file), "utf8").trim().split("\n");
  const header = lines[0].split(",");
  return lines.slice(1).map((line) => {
    const cells = line.split(","); // 単純な区切り。件名にカンマがあると列がずれる（記事 第3.2節）
    const row = {};
    header.forEach((h, i) => (row[h] = cells[i]));
    if (cells.length !== header.length) row["_注意"] = `列数が ${cells.length}（見出しは ${header.length}）`;
    return row;
  });
}
function readJson(file) {
  return JSON.parse(fs.readFileSync(path.resolve(__dirname, file), "utf8"));
}
function countByState(rows) {
  const counts = {};
  for (const r of rows) counts[r["状態"]] = (counts[r["状態"]] || 0) + 1;
  return counts;
}

const targets = process.argv[2] ? [process.argv[2]] : ["requests.csv", "requests.json"];
for (const file of targets) {
  const rows = file.endsWith(".json") ? readJson(file) : readCsv(file);
  console.log(`=== ${file}（入力データ）===`);
  for (const r of rows) console.log("読んだ1件:", JSON.stringify(r));
  console.log("状態ごとの件数（出力）:", JSON.stringify(countByState(rows)));
}

「入力→判断・処理→出力→失敗時」の対応：

読み違えを観察するための入力データも用意しています（requests-comma.csv）。3件目の件名を「プロジェクタ,予備電池の発注」と、カンマを含む件名にしてあります。

依頼ID,依頼者,件名,状態,提出日
REQ-0001,佐藤,会議室の予約,提出済み,2026-09-18
REQ-0003,鈴木,プロジェクタ,予備電池の発注,提出済み,2026-09-19

6. 実行結果

examples/00-02-file-structure/ で実行した stdout と終了コードです（整形・省略なし。stderr への出力はありませんでした）。

CSVとJSONを同じプログラムで読んだ場合：

$ node count_by_state.js
=== requests.csv（入力データ）===
読んだ1件: {"依頼ID":"REQ-0001","依頼者":"佐藤","件名":"会議室の予約","状態":"提出済み","提出日":"2026-09-18"}
読んだ1件: {"依頼ID":"REQ-0002","依頼者":"田中","件名":"備品の発注","状態":"承認済み","提出日":"2026-09-15"}
状態ごとの件数（出力）: {"提出済み":1,"承認済み":1}
=== requests.json（入力データ）===
読んだ1件: {"依頼ID":"REQ-0001","依頼者":"佐藤","件名":"会議室の予約","状態":"提出済み","提出日":"2026-09-18"}
読んだ1件: {"依頼ID":"REQ-0002","依頼者":"田中","件名":"備品の発注","状態":"承認済み","提出日":"2026-09-15"}
状態ごとの件数（出力）: {"提出済み":1,"承認済み":1}
終了コード: 0

CSVとJSONは形式が違っても、同じ内容なら同じ1件ずつが読め、同じ件数（提出済み1件、承認済み1件）になります。

件名にカンマを含むCSVを読んだ場合：

$ node count_by_state.js requests-comma.csv
=== requests-comma.csv（入力データ）===
読んだ1件: {"依頼ID":"REQ-0001","依頼者":"佐藤","件名":"会議室の予約","状態":"提出済み","提出日":"2026-09-18"}
読んだ1件: {"依頼ID":"REQ-0003","依頼者":"鈴木","件名":"プロジェクタ","状態":"予備電池の発注","提出日":"提出済み","_注意":"列数が 6（見出しは 5）"}
状態ごとの件数（出力）: {"提出済み":1,"予備電池の発注":1}
終了コード: 0

結果の読み方：2件目は、件名の途中のカンマで区切られ、「状態」の欄に「予備電池の発注」、「提出日」の欄に「提出済み」が入っています。その結果、状態ごとの件数に「予備電池の発注：1件」という存在しない状態が現れます。エラーは出ず、終了コードも0です。読み違えは「止まる」のではなく「間違った答えが静かに出る」形で起きます。これが、第3.2節の3つ目の例です。

7. 確認結果

実行環境：macOS 26.6.2、Node.js v24.18.0（node:fs・node:path のみ使用）、2026-09-20に実行。教材演習用のフォルダ（examples/00-02-file-structure/）の中で行い、何も書き換えていません。stdout・stderr・終了コードをそのまま記録した実行記録は第9節の run_log.md にあります。

完了条件との照合：

残る制限：文字コードの違いによる文字化けと、日付表記の不統一は、この記事では説明にとどめ、実際には起こしていません（起こす場合は保存時の設定を変える必要があり、この記事の範囲を超えます）。出力は画面表示だけで、出力ファイルは作っていません。この記事の本文と記入例はClaude Codeが作成したもので、業務担当者による内容確認は行っていません。

8. 設計を判断する

8.1 依頼データの形式候補を比較する

依頼と履歴という「1件に対して複数」の関係（05-01で扱う内容）を考えると、JSON、またはそれに近い構造を扱えるデータベースの形式が候補になりやすいという論点が残ります。この記事ではどちらかに確定せず、05-01へ論点として持ち越します。この教材の実装（08-02以降）が保存先にJSONファイルを使っているのは、この論点を踏まえた教材演習用の選択であり、正式な技術選定（03-03）ではありません。

8.2 適用限界

この比較は、架空の小さな依頼一覧を前提にした一例です。実際にデータ量が増えた場合の扱いやすさの違いは、この記事では確認していません。

9. 持ち帰る成果物

自分の業務に使うときの手順は次のとおりです。

1. 自分の業務で扱うデータを1つ選び、それが「入力データ」であることを確かめる（第4節）
2. そのデータをCSV・JSONの両方で小さく書いてみる
3. 文字コード・日付表記・区切り文字など、読み違えが起きそうな点を書き出す
4. できれば最小のプログラムで読んで、同じ結果になるか、ずれが起きないかを見る

10. 次工程への受渡し

次へ渡すもの：基本用語の対応表、CSV・JSONの架空データの例、形式候補の論点（第8.1節）。

次工程での使われ方：06-01（作業場所と実行環境を整える）では、この記事のファイル構成の考え方を作業フォルダの土台にします。05-01（データ項目と関係を決める）では、この記事で残した形式候補の論点を引き継ぎます。08-02では、入力データを読むだけでなく、保存して書き換える処理を扱います。

前工程へ戻る条件：この記事の例が00-01の見取り図（保存先の役割）と食い違う場合は、00-01に戻って確認します。

11. 根拠と更新情報

• この記事の会社・人物・データはすべて架空の設定です。
• CSV・JSONの例、文字コード・日付表記の注意点は、教材設計書AI_SYSTEM_DEV_BLUEPRINT_v0.1.md第4.1節の基礎テーマ配置（文字コード、CSV、JSON、日付・時刻の初出をこの記事とする）に基づきます。
• 制作の来歴：本文・ひな形・記入例はClaude Codeが作成しました。第5.4節・第6節の最小例は examples/00-02-file-structure/ を正本とし、2026-09-20にmacOS 26.6.2・Node.js v24.18.0の環境で実際に実行して、stdout・stderr・終了コードを evidence_public/phase5b2a-2026-09-20/00-02/run_log.md に記録しています。人（ユーザー）による実読・内容確認は未実施です。
• 2026-09-20（Phase 5B-2A）：受入監査で「完了条件『プログラム・入力データ・出力の3つが別ファイルとして例示』に対し、本文は表で種類を挙げるだけで実物が無い」と指摘された。読み込んで表示するだけの最小のプログラムと入力データを examples/ に置き、実際に実行した結果に置き換えた。あわせて読む順路（3つの深さ）、第4節の判断項目、記事間の参照を追加した。用語説明・CSV/JSONの例・第8節の比較は変えていない。
• 未確認事項：文字コードの違いによる文字化けと日付表記の不統一は、説明にとどめ、実際には起こしていません（第7節）。