{"id":50887516,"url":"https://github.com/9uile/ema","last_synced_at":"2026-06-15T18:01:17.777Z","repository":{"id":362873131,"uuid":"1261070270","full_name":"9uiLe/ema","owner":"9uiLe","description":"「流暢性の罠」を断つ ADR ワークフロー CLI。AI 生成 Markdown の“分かった気”による誤承認を、反証スロット付きの生成 HTML へのレビューで防ぐ。外部依存ゼロ（Node 標準のみ）。","archived":false,"fork":false,"pushed_at":"2026-06-06T09:16:16.000Z","size":95,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-06T11:10:43.214Z","etag":null,"topics":["adr","architecture-decision-records","cli","zero-dependencies"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/9uiLe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-06T07:41:05.000Z","updated_at":"2026-06-06T09:34:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/9uiLe/ema","commit_stats":null,"previous_names":["9uile/ema"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/9uiLe/ema","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9uiLe%2Fema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9uiLe%2Fema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9uiLe%2Fema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9uiLe%2Fema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/9uiLe","download_url":"https://codeload.github.com/9uiLe/ema/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9uiLe%2Fema/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34374146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adr","architecture-decision-records","cli","zero-dependencies"],"created_at":"2026-06-15T18:01:16.271Z","updated_at":"2026-06-15T18:01:17.772Z","avatar_url":"https://github.com/9uiLe.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ema — 流し読みを防ぐ ADR ワークフロー\n\nAI が生成した Markdown は **スラスラ読めてしまう**。その読みやすさ（処理流暢性）を理解と取り違えると、**承認した後で「なんか違う」** が起きる。このリポジトリは、その誤承認を構造的に防ぐための ADR（Architecture Decision Record）ワークフローと、外部依存ゼロの統一 CLI `ema` を提供する。\n\n中心にある運用規律はひとつ：**承認は生 diff ではなく、生成された HTML の描画に対して行う。** 固定スロット・反証スロット・比較表・読む摩擦を備えた HTML を見ながらレビューすることで、流し読みを防ぐ。\n\n- **正本は Markdown**（`docs/decisions/NNNN-slug.md`）。AI ネイティブで書きやすく、git で差分が読める。\n- **レビュー用 HTML は生成物**（`ema gen`）。`.md` だけをコミットし、`.html` はビルドで作る。\n- **外部依存ゼロ**（Node 標準モジュールのみ）。`package.json` の `dependencies` は空。\n\n\u003e なぜこの形なのかは、リポジトリ自身の ADR が決定として残してある（下記「設計判断」）。\n\n## セットアップ\n\n対象は Node を持つ開発者。各 PC で一度だけ：\n\n```bash\ngit clone \u003cthis-repo\u003e \u0026\u0026 cd ema\nnpm link          # PATH に `ema` コマンドを生やす（冪等・Win/macOS/Linux）\n```\n\nnpm を使いたくなければセットアップ不要で、同じことができる：\n\n```bash\nnode bin/ema.mjs \u003ccommand\u003e       # 例: node bin/ema.mjs lint\nnpm run \u003cscript\u003e                 # 例: npm run lint  （new/gen/lint/view/check/test）\n```\n\n必要環境: **Node.js \u003e= 20**（`node:test`・recursive `fs.watch` が安定）。\n\n## 使い方\n\n```bash\nema new \"キャッシュ層の導入\" cache-layer   # 次番号を採番し、固定/反証スロット入り .md を作成\nema lint                                   # 固定スロット・反証スロットの充足を検査\nema gen                                    # docs/decisions/*.md → レビュー用 HTML を生成\nema view                                   # ローカルビューアを起動（ライブリロード）。ここで承認する\nema help                                   # サブコマンド一覧\nema \u003ccommand\u003e --help                       # 各コマンドの詳細\n```\n\n典型的な流れ：\n\n```bash\nema new \"決定タイトル\" decision-slug             # 雛形を作る\n$EDITOR docs/decisions/0005-decision-slug.md     # Context / Options / Decision / 反証 を埋める\nema lint docs/decisions/0005-decision-slug.md    # スロット充足を確認\nema gen \u0026\u0026 ema view                              # 描画を見ながらレビュー → 承認\n```\n\n| コマンド | 役割 |\n|---|---|\n| `ema new \"\u003ctitle\u003e\" [slug]` | 次番号を採番し、テンプレ（固定スロット＋反証スロット）から `.md` を生成。既存は上書きしない |\n| `ema gen [files...] [--check]` | Markdown 正本 → デザインシステム HTML。`--check` は生成せず不整合のみ検出（CI 用） |\n| `ema lint [files...]` | frontmatter 必須キーと固定/反証スロットの充足を検査（ERROR があれば終了コード 1） |\n| `ema view [dir] [--port N] [--no-open]` | `docs/decisions/` を配信＋一覧自動生成＋ライブリロードするローカルビューア |\n\n\u003e 対象 `docs/decisions/` は **git と同じように cwd から上に辿って探す** — リポジトリ内のどのサブディレクトリから `ema` を叩いても、その repo の `docs/decisions/` を見つける。見つからなければ、`npm link` した clone 自身の `docs/decisions/` にフォールバックする。`ema view \u003cdir\u003e` で対象ディレクトリを明示することもできる。\n\n## プロジェクト構成\n\n```\nbin/\n└── ema.mjs                 # 実行エントリ（薄いディスパッチャ。new|gen|lint|view|help を委譲）\nsrc/\n├── commands/\n│   ├── new.mjs             # 雛形生成\n│   ├── gen.mjs             # 生成\n│   ├── lint.mjs            # 検査\n│   └── view.mjs            # ビューア\n├── render.mjs              # Markdown→HTML の純粋変換ロジック（副作用なしの seam・テスト対象）\n└── paths.mjs               # 対象 docs/decisions/ の解決（cwd 上り探索）\ntest/\n├── render.test.mjs         # node:test の回帰テスト（依存ゼロ）\n└── paths.test.mjs\ndocs/\n├── decisions/              # ADR 正本(.md) ＋ 生成HTML(.html)\n│   ├── 0000-…              # テンプレート＆レビュー観点（lint が機械強制する対象）\n│   ├── 0001-…〜0005-…      # 確定した設計判断（下記）\n│   └── assets/             # 描画用デザインシステム（tokens.css / components.css 等）\n└── format.md               # 制約付き Markdown の記法仕様\npackage.json                # 依存ゼロのマニフェスト（bin: ema / scripts / engines）\n```\n\nCLI（`src/commands/*.mjs`）はファイル IO と引数解析だけを担い、変換ロジックは副作用のない `src/render.mjs` に分離してある。これにより `node:test` で描画の正しさを回帰テストでき、「承認は描画でする」運用の土台が崩れないことを担保する。各 `src/commands/\u003ccmd\u003e.mjs` は `node src/commands/\u003ccmd\u003e.mjs` の直接起動も後方互換で残している。\n\n## 開発\n\n```bash\nnpm test          # = node --test（依存ゼロのユニットテスト）\nnpm run check     # = ema gen --check（HTML が正本と一致するか。CI 用）\n```\n\n記法を拡張するときは **回帰テストを先に書く**（`test/render.test.mjs`）。実行時依存は追加しない方針（追加は打診の上、ADR の撤回トリガーに照らして判断）。テスト実行は `node --test`（引数なし自動探索）を使う。\n\n## 設計判断（このリポジトリ自身の ADR）\n\nこのツール群は、自分の決定を自分のフォーマットで残している（ドッグフーディング）。\n\n| ADR | 内容 |\n|---|---|\n| [ADR-0000](docs/decisions/0000-adr-template-and-review-guide.md) | ADR テンプレートとレビュー観点（反証スロット必須） |\n| [ADR-0001](docs/decisions/0001-local-adr-viewer.md) | ローカル ADR ビューア |\n| [ADR-0002](docs/decisions/0002-adr-source-format.md) | 正本形式：AI ネイティブな Markdown を正本とし、HTML を生成する |\n| [ADR-0003](docs/decisions/0003-adr-tooling-stack.md) | 技術スタック：ゼロ依存を維持し試験性は `node:test` で確保（→ 0004 が更新） |\n| [ADR-0004](docs/decisions/0004-cli-and-distribution.md) | 配布と CLI：公開・チーム前提でも Node を継続し、設置性は `package.json` で埋める |\n| [ADR-0005](docs/decisions/0005-modernize-naming-layout.md) | ディレクトリ・命名のモダン化（`bin/`+`src/`+`docs/decisions/`、コマンド `ema`） |\n\n各 ADR には「**この決定が間違いになるとしたら何が原因か**」を観測可能なトリガー付きで明記してある。前提が崩れたら、そのトリガーに従って決定を引き直す。\n\n\u003e ADR 0000–0004 の本文に出てくる旧パス（`tools/…`）・旧コマンド（`adr …`）は、決定当時の記録としてそのまま残している。現行の対応は ADR-0005 の旧→新マッピング表が正。\n\n## ライセンス\n\n[MIT](LICENSE)。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F9uile%2Fema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F9uile%2Fema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F9uile%2Fema/lists"}