エージェントに一文でシステム全体を生成させないでください。「IT 資産管理システムを作って」では何十もの業務上の疑問が未決のまま残り、エージェントは推測するしかありません。まずエージェントと設計を話し合い、リポジトリにドキュメントとしてまとめ、以降の要件はすべてそれに基づいて出します。
1. エージェントと設計を話し合う
itam-lite ディレクトリで新しいセッションを始めます。
シンプルな IT 資産管理システムを作りたいです。まだコードは書かずに、先に設計を固めましょう。
ロールは 3 つです。従業員がデバイスを申請し、資産管理者が承認し、IT サポートが貸与して台帳に記録します。
私が決める必要があることは、1 グループずつ質問してください。それぞれにあなたのおすすめも添えてください。エージェントは 1 グループずつ質問します。このチュートリアルでは次のように決めました。
| エージェントの質問 | 決定 |
|---|---|
| デバイスにはどんな項目があるか。資産番号とシリアル番号は一意か | 資産番号は必須で一意。シリアル番号は任意 |
| どの申請に承認が必要か | ノート PC とスマートフォンは承認が必要。すでに使用中のデバイスが 2 台ある人の申請も承認が必要。どちらも管理者が調整できる |
| だれが承認し、だれが貸与するか | 資産管理者のだれかが承認するが、自分の申請は承認できない。IT サポートが在庫のあるデバイスを選んで貸与する |
| 従業員は何を見られるか | 自分の申請と、自分に割り当てられたデバイスだけ |
| このバージョンの対象外は何か | 購買、修理、棚卸し、廃棄、返却、多段階承認、インポートとエクスポート |
| 会社のデザインシステムはあるか | ない。NocoBase 3 に組み込まれたデザイン規約を使う |
会社のデザインシステム（色、フォント、コンポーネントのルール）がある場合は、そのファイルをリポジトリに置き、このステップでエージェントに伝えてください。
2. 設計書にまとめる
決まった設計を docs/design.md に書いてください：ロール、データ、ワークフロー、ページ、権限、さらにステップごとの引き渡し計画と、各ステップの検収基準。
AGENTS.md に登録してください：業務上の変更の前には必ず読むこと。要件が設計を変える場合は、先に設計書を更新してからコードを変更すること。エージェントが書いた設計書は、サンプルリポジトリの docs/design.md です。最後のセクションでは開発を 3 つのステップに分けており、それがちょうど次の 3 ページになります。
| ステップ | 引き渡すもの | 完了の条件 |
|---|---|---|
| 1 デバイス台帳 | デバイスのテーブル、API、ページ | デバイスを作成、編集、検索できる。資産番号が重複すると入力欄の横にメッセージが表示される。再読み込みしてもデータが残っている |
| 2 申請と承認 | 申請、ワークフロー、通知、ワークフロー管理 | ノート PC の申請が承認され、IT サポートが貸与すると、台帳でデバイスが In use になる。モニターの申請はそのまま Ready to issue になる。関係者にアプリ内メッセージが届く |
| 3 ロールと権限 | 3 つのロールとそのデータ範囲 | 3 つのアカウントでそれぞれサインインすると、見えるものとできることが権限マトリクスと一致する。ロールの権限を超える API 呼び出しは拒否される |
設計書に目を通し、間違っているところがあればエージェントに直してもらいます。
より体系的な進め方には、OpenSpec（変更ごとに提案、設計、タスクとしてまとめる）や superpowers（ブレインストーミング、計画、実行の順に進める）を使えます。
3. 以降の要件では毎回 3 つの点を書く
設計書はシステム全体を扱います。個々の要件では、業務の言葉で 3 つの点を書きます。
- だれが使うか。
- 何をするか。
- ルール：だれが何をできるか、どのデータに触れてはならないか。
同じ要件を 2 通りに書くと：
デバイスを返却できるようにしてください。デバイス台帳に「返却」を追加してください。
IT サポートは In use のデバイスで「返却」をクリックし、返却場所を入力します。デバイスは In stock になり、使用者はクリアされます。
返却できるのは IT サポートと資産管理者だけで、従業員はできません。In stock、In repair、Retired のデバイスは返却できません。1 つ目では、だれが返却でき、ステータスがどう変わるかをエージェントが推測するしかありません。2 つ目なら、エージェントは推測せずにそのとおりに進められ、計画も明確になります。
大きな要件では、先にエージェントに計画を提案させ、確認してから始めてもらいます。
まだコードは変更しないでください。この変更がどの部分にかかわるか、私が決める必要がある質問、どう検証するつもりかを一覧にしてください。要件の書き方と結果の検収については、アプリの開発を続ける を参照してください。
完了の条件リポジトリに docs/design.md があり、AGENTS.md の索引に登録されていて、設計書の最後にステップごとの引き渡し計画と各ステップの検収基準があること。