大切な意図を書く

意図ドキュメントには、ソフトウェアが満たすべき動作と制約を書きます。決まったことを書き、実装や根拠から学びながら磨きます。読みやすさを保ちつつ、Agent に実装の余地を残せます。

残す価値のある要件を選ぶ

意図にはさまざまな要件を書けます。

起動条件と観察可能な結果を書きます。「エクスポートは信頼できること」は確認しにくいですが、「失敗したら現在のフィルターを保持し、再試行できること」なら評価基準が明確です。

今後の変更でも守るほど重要な実装上の選択は、意図に記録します。まだ決めていない詳細は、実装側の選択のままで構いません。

継続的な要件と今回の作業を分ける

意図はソフトウェアが継続して行うべきことです。完了後に消すチェックリストではありません。機能完成後も残し、動作を変えると決めたときに該当箇所を変更します。

チャットには今回の作業指示もあります。次のように区別します。

文が何を制約するか考えます。「毎回エクスポート前にデータを検証する」はソフトウェアの実行順序なので意図です。「今回は先にエクスポートモジュールを調べる」は今回の作業の進め方です。

継続的な要件と今回だけの指示を Agent に伝えます。重要な作業指示は必要に応じて繰り返し、新しいチャットが引き継ぐと思い込まないでください。

ドキュメントを作成・編集する

サイドバーの新規意図で名前を入力します。意図フォルダのルートに、一段階目の見出しを持つ .noea.md が作成されます。

Markdown を使い、同じ画面で閲覧と編集を行います。文章をクリックして編集し、見出し、リスト、表、コードブロックで整理します。

例：

# 毎日のチェックイン

ユーザーは一日一回チェックインできる。

## 報酬

7 日連続でチェックインしたユーザーに報酬を付与する。同じ連続期間内の付与は一回だけとする。

見出しで節を分け、異なる要件は段落に分けます。リスト全体は一つの内容として調査されます。個別に調査・相談したい話題は別の段落や節にします。

話し合いながら意図を育てる

ルールが曖昧なら、変更提案を依頼する前に相談します。

チェックイン報酬の重複を防ぎたいです。ここでの「重複」の定義を一緒に考え、私が確認してから意図の変更を提案してください。

判断が決まったら、提案にするよう依頼します。文章をレビューし、必要なら新しい文章を編集して承認します。チャットの発言は、ドキュメントに書かれて初めて意図の一部になります。

文章は自分が理解できる概念と言葉にします。未知の用語や追加要件は、採用を決める前に質問してください。よい文章なら自分で要件を説明でき、動作を変えるときに直す文を見つけられます。

変更提案とメモのカードについては、意図の変更を相談・レビューするをご覧ください。

図で関係を表す

言語を mermaid としたコードブロックは図として表示できます。状態遷移、ワークフロー、モジュール間の関係に使えます。

右上の操作で図とソースを切り替えます。編集はソースで行います。構文が無効、または図の種類が未対応なら、ソースと理由を表示し、残りの文章は読めるままです。

保存と外部エディタの利用

macOS は ⌘S、Windows / Linux は Ctrl+S、またはファイル → 保存で手動保存します。タイトル横の点は未保存の変更です。タブを切り替えても保持され、ドキュメントやプロジェクトを閉じるとき、アプリ終了時には保存を確認します。

保存時に Markdown の書式が整えられます。外部エディタで管理しても構いません。Noea で編集中にディスク上のファイルが変わると、直接上書きせず、再読み込みや別名保存を案内します。

文章変更の意味を理解する

追加、置換、削除はそれぞれ要件に異なる影響を与えます。

バッジの要件を消しても、既存のバッジ実装が必ず不適切になるわけではありません。残る意図を満たす可能性があります。報酬そのものを廃止したいなら、形式の要件を消すだけでなく、報酬を付与しないと明記します。

編集前に、どの動作が変わり、どの要件を維持すべきか Agent に質問できます。回答を議論の材料とし、実際の実装と根拠を確認します。

保存後、古い説明には以前のテキストと表示されます。新要件にコード変更が必要なら実装後に調査し、既存動作だけを確認するなら直接調査します。

Agent と実装を進める、または説明を最新に保つに進みましょう。