<h3 align="center">visual-spec（日本語）</h3>
<p align="center">「一文要件」から実行可能プロトタイプと追跡可能な仕様へ。段階的な <code>/vspec:*</code> ワークフローで手戻りと齟齬を減らします。</p>
<p align="center">
  <a href="https://github.com/visual-req/visual-spec/releases"><img src="https://img.shields.io/github/v/release/visual-req/visual-spec" alt="Release"></a>
  <a href="https://github.com/visual-req/visual-spec"><img src="https://img.shields.io/github/stars/visual-req/visual-spec?style=flat-square" alt="Stars"></a>
  <a href="https://github.com/visual-req/visual-spec/issues"><img src="https://img.shields.io/github/issues/visual-req/visual-spec?style=flat-square" alt="Issues"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a>
</p>
<p align="center">
  <a href="README.md">English</a> · <a href="README-zh-CN.md">中文</a> · <a href="README-ja-JP.md">日本語</a>
  <br/>
  <a href="docs/ja-JP/getting-started.md">クイックスタート</a> · <a href="docs/ja-JP/commands.md">コマンド</a> · <a href="docs/ja-JP/workflows.md">ワークフロー</a> · <a href="docs/ja-JP/theory.md">方法論</a>
</p>
<hr />

バージョン：0.1.13（2026-04-12）· License: MIT（[LICENSE](LICENSE)）

## 3 行クイックスタート

- インストール：`npx skills add visual-req/visual-spec --skill visual-spec`
- 実行：`/vspec:new` を実行し、最小要件（下記）を貼り付け
- 成果物：`/vspec:verify` → `/specs/prototypes/` に実行可能プロトタイプ

最小入力例：

> 会社には多くの車両（セダンやマイクロバス）と多くのドライバーがいます。社員は業務に応じて車両を申請し、配車担当は乗客人数と走行ルートに基づいて適切な車両を割り当てます。ドライバーは出発と到着を正確に記録し、配車プロセスを標準化して管理します。

## 30 秒でわかる価値

入力（生の要件）：

> 「チームのタスクボード。プロジェクト作成、タスク割当、個人別の進捗集計ができる。」

`/vspec:new` → `/vspec:verify` の後に得られるもの：

- 実行可能プロトタイプ + シナリオレビュー入口
- 構造化仕様：ロール/シナリオ/フロー/機能分解と詳細
- データモデル、および権限/バリデーション/ロジックをレビューするための仕様

## クイックスタート（3 ステップ）

```bash
npx skills add visual-req/visual-spec --skill visual-spec
```

2. `/vspec:new` を実行し、要件テキストを貼り付けます。
3. Open Questions に答えた後、`/vspec:verify` を実行して実行可能プロトタイプでレビューします。

初心者向け： [docs/ja-JP/getting-started.md](docs/ja-JP/getting-started.md)

## 想定ユーザー

| プロダクト / BA | 開発 | QA / 受入 |
| --- | --- | --- |
| 曖昧な要件をレビュー可能なシナリオと原型へ | 実装/テスト可能な詳細（権限/検証/ロジック）とモデル | 重要シナリオを受入ケースへ落とし込む |

## Overview

ワークフロー図（SVG）：

![visual-spec workflow](docs/assets/ja-JP/visual-spec-workflow.svg)

方法論 / theory（全体設計の考え方とコマンド分割の意図）：
- [docs/ja-JP/theory.md](docs/ja-JP/theory.md)

ステージマップ（SVG）：

![visual-spec stage map](docs/assets/ja-JP/visual-spec-stage-map.svg)

- 要件分析：背景、ステークホルダー、ロール、用語、フロー、シナリオ、詳細、依存関係、機能一覧、未解決質問を生成
- 方案検証：データモデル、実行可能プロトタイプ、シナリオレビュー用ページを生成
- プロトタイプ生成（高頻度）：`/vspec:verify` が `/scheme.yaml` に合わせて実行可能な Web プロトタイプを生成（`/specs/prototypes/`）。ロール別ダッシュボード（適切なチャート選定/配置）とシナリオレビュー用ページを含む
- 詳細設計：機能ごとに RBAC/データ権限/インタラクション/バリデーション/ログ/通知/MQ/入出力/定期実行 spec を生成
- 受入 & テスト：受入ケースと自動テストコードを生成
- 統合実装：リポジトリの実スタック/規約に合わせて backend + frontend の統合コード生成
- 計画：機能一覧に基づき見積とスケジュール（HTML）を生成

## Commands

| コマンド | 用途 | 主なメリット | 主な出力 |
| --- | --- | --- | --- |
| `/vspec:new` | ベースライン spec の生成 | 生の要件をレビュー可能な構造へ落とし込む | `/specs/`（background/functions/flows 等） |
| `/vspec:detail` | 機能ごとの詳細 spec | 実装/テスト可能な粒度へ展開する | `/specs/details/` |
| `/vspec:verify` | モデル + 実行可能プロトタイプ | 期待どおりの振る舞いか早期に確認できる | `/specs/models/`、`/specs/prototypes/` |
| `/vspec:qc` | 品質チェック | 漏れ/矛盾/テスト不能/追跡不足を早期に可視化する | `/specs/qc_report.json`、`/specs/qc_report.html` |
| `/vspec:refine` | 要件の修正と下流成果物の同期更新 | 変更時に成果物の整合を保つ | `original.md` 更新 + 影響範囲の同期更新 |
| `/vspec:accept` | 受入ケース生成（JSON） | シナリオを実行可能な受入ケースに落とす | `/test/验收用例/acceptance_cases.json` + `/test/testcase_reader.html` |
| `/vspec:i-test` | 単体/結合テストケース（JSON） | ロジック/権限/分岐のカバレッジを明示する | `/test/单元测试/unit_test_cases.json`、`/test/集成测试/integration_test_cases.json` + `/test/testcase_reader.html` |
| `/vspec:script` | Playwright スクリプト生成 | JSON ケースから自動化骨格を生成する | `/test/playwright/acceptance.spec.ts`、`/test/playwright/integration.spec.ts` |
| `/vspec:append-test` | 自動テストコード生成 | テスト自動化の導入コストを下げる | 既存テストディレクトリ or `/tests/` |
| `/vspec:impl` | 統合実装入力の生成 | スタック/規約に合わせた実装入力を出す | `/specs/backend/`（有効時）および関連コード |
| `/vspec:plan` | 見積・排期 | スコープをレビュー可能な計画にする | `/specs/plan/plan_estimate.md`、`/specs/plan/plan_schedule.html` |
| `/vspec:upgrade` | 既存資料から specs を再生成/更新 | 既存資料から仕様を再構築/更新する | `/specs/` 更新 + 技術選定を `/scheme.yaml` に同期 |

見積・排期（Plan）機能だけを単独で使いたい場合（visual-spec のフルワークフロー不要）は、こちらを利用してください： https://github.com/visual-req/project-plan

品質チェック（QC）機能だけを単独で使いたい場合（visual-spec のフルワークフロー不要）は、こちらを利用してください： https://github.com/visual-req/spec-review

## Documentation

| Doc | 説明 | Link |
| --- | --- | --- |
| Getting started | ワークフローを通しで実行 | [docs/ja-JP/getting-started.md](docs/ja-JP/getting-started.md) |
| Commands | `/vspec:*` の参照 | [docs/ja-JP/commands.md](docs/ja-JP/commands.md) |
| Structure | ディレクトリ構成と成果物 | [docs/ja-JP/structure.md](docs/ja-JP/structure.md) |
| Workflows | ワークフロー概要 | [docs/ja-JP/workflows.md](docs/ja-JP/workflows.md) |
| Installation | インストール（英語） | [docs/en-US/installation.md](docs/en-US/installation.md) |
| Troubleshooting | よくある問題と対処 | [docs/ja-JP/troubleshooting.md](docs/ja-JP/troubleshooting.md) |
| Fork guide | fork 後のカスタマイズ | [docs/ja-JP/fork.md](docs/ja-JP/fork.md) |

## upgrade と refine の違い

- `upgrade`：遺留システムのアップグレード/刷新向け。`/docs/legacy/` と `/docs/current/`（および templates/texts/assets）を入力として、アップグレード後の target spec と技術選定を生成/更新する。
- `refine`：visual-spec で分析済みで、visual-spec の構造で保存されている要件（遺留/新規を問わない）を継続的に修正し、下流成果物（details/プロトタイプ/backend 実装があれば）との整合を保つ。

## Directory Structure

- `skills/visual-spec/SKILL.md`：Skill 定義
- `skills/visual-spec/prompts/`：各コマンドのプロンプト

## FAQ

- 技術スタックに合わせられますか？  
  `/vspec:verify` のプロトタイプは Web 形態で、`/scheme.yaml` に従います。参考： [scheme.example.yaml](docs/en-US/scheme.example.yaml) と [docs/ja-JP/structure.md](docs/ja-JP/structure.md)。
- 成果物はどこに出力されますか？  
  主に `/specs/` 配下（models、prototypes、details、qc report、plan）と `/test/` 配下（JSON テストケース、Playwright スクリプト）です。参考： [docs/ja-JP/structure.md](docs/ja-JP/structure.md)。
- Troubleshooting（よくある問題と対処）  
  参照： [docs/ja-JP/troubleshooting.md](docs/ja-JP/troubleshooting.md)。

## Contributing

- カスタマイズ： [docs/ja-JP/fork.md](docs/ja-JP/fork.md)
- 改善提案・不具合報告：GitHub Issues / Pull Requests
