note-it

実装メモ

Issue の実装とレビュー／修正が完了したら、実装が仕様とどのように異なるか、または仕様をどのように解釈したかを記録した、随時更新する実装メモファイルを作成します。

トリガー

次の場合に使用します。

• /goal による実装と /review-it の両方が完了した後
• ユーザーが「记录笔记」、「implementation notes」、「note-it」、「/note-it」と言ったとき
• /ship-it の前（最終チェックポイントとして）
• ユーザーが設計上の判断理由を記録したいとき

作業内容

1. コンテキスト（ブランチ名、/goal の対象、またはユーザーの入力）から Issue 番号を特定します
2. Issue の仕様／PRD と実装を照らし合わせて確認します
3. docs/issue#XXXX.html に HTML 形式のメモファイルを生成します
4. ユーザーに概要を提示します

メモの構成

HTML ファイルには、次の 4 つのカテゴリを含める必要があります。報告事項がないカテゴリには、簡単な説明を添えて「None」と記載します。

1. 設計上の判断

仕様が曖昧、または明記されていない箇所で行った選択：

• 何が曖昧でしたか？
• どのような選択をしましたか？
• その判断理由は何ですか？

2. 仕様からの逸脱

意図的に仕様と異なる対応をした箇所：

• 仕様には何と書かれていましたか？
• 代わりに何を実装しましたか？
• なぜその逸脱が必要、またはより適切でしたか？

3. トレードオフ

検討した代替案と、選択した理由：

• 実行可能な代替案には何がありましたか？
• それぞれの長所と短所は何ですか？
• なぜこの方法を選びましたか？

4. 未解決の質問

確認または見直しが必要な事項：

• どのような前提に確信が持てませんか？
• ユーザーは何を確認すべきですか？
• どのようなフォローアップが必要になる可能性がありますか？

出力

• 形式： HTML
• 場所： docs/
• ファイル名： issue#XXXX.html（XXXX はゼロ埋めした Issue 番号。例：issue#0042.html）

HTML テンプレート

次の HTML 構造をそのまま使用します。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Implementation Notes — Issue #XXXX</title>
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
      background: #FAF9F6;
      color: #1a1a1a;
      padding: 2.5rem 2rem;
      line-height: 1.7;
    }
    .container { max-width: 800px; margin: 0 auto; }
    h1 { font-size: 1.375rem; font-weight: 700; margin-bottom: 0.25rem; }
    .meta { color: #8B8680; font-size: 0.8125rem; margin-bottom: 2rem; }
    h2 {
      font-size: 1rem;
      font-weight: 600;
      margin-top: 2rem;
      margin-bottom: 0.75rem;
      padding-bottom: 0.375rem;
      border-bottom: 1px solid #E8E4DE;
      display: flex; align-items: center; gap: 0.5rem;
    }
    .dot {
      width: 8px; height: 8px; border-radius: 50%; display: inline-block;
    }
    .dot.design { background: #5B8A72; }
    .dot.deviation { background: #D97757; }
    .dot.tradeoff { background: #4A6FA5; }
    .dot.question { background: #D4A843; }
    .item {
      background: #FFFFFF;
      border: 1px solid #E8E4DE;
      border-radius: 8px;
      padding: 1rem 1.25rem;
      margin-bottom: 0.75rem;
      box-shadow: 0 1px 3px rgba(0,0,0,0.03);
    }
    .item h3 { font-size: 0.875rem; font-weight: 600; margin-bottom: 0.375rem; }
    .item p { font-size: 0.8125rem; color: #4A4540; margin-bottom: 0.375rem; }
    .label {
      display: inline-block;
      font-size: 0.6875rem;
      font-weight: 500;
      padding: 0.125rem 0.5rem;
      border-radius: 4px;
      margin-right: 0.375rem;
    }
    .label-design { background: #F5F8F6; color: #5B8A72; border: 1px solid #5B8A72; }
    .label-deviation { background: #FFF5F0; color: #D97757; border: 1px solid #D97757; }
    .label-tradeoff { background: #F0F4F8; color: #4A6FA5; border: 1px solid #4A6FA5; }
    .label-question { background: #FDF8F0; color: #D4A843; border: 1px solid #D4A843; }
    .none { color: #B0AAA4; font-style: italic; font-size: 0.8125rem; }
    .footer {
      text-align: center; margin-top: 2.5rem; color: #B0AAA4;
      font-size: 0.6875rem;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>Implementation Notes</h1>
    <p class="meta">Issue <a href="{{ISSUE_URL}}">#{{ISSUE_NUMBER}}</a> &mdash; {{ISSUE_TITLE}} &mdash; {{DATE}}</p>

    <h2><span class="dot design"></span> Design Decisions</h2>
    

    <h2><span class="dot deviation"></span> Deviations</h2>
    

    <h2><span class="dot tradeoff"></span> Tradeoffs</h2>
    

    <h2><span class="dot question"></span> Open Questions</h2>
    

    <p class="footer">Generated by goal-workflow /note-it</p>
  </div>
</body>
</html>

項目の例

<div class="item">
  <h3><span class="label label-design">Decision</span> Used interface-based polymorphism instead of switch</h3>
  <p><strong>Ambiguity:</strong> The spec said "handle different types" without specifying how.</p>
  <p><strong>Choice:</strong> Defined a <code>Handler</code> interface with per-type implementations.</p>
  <p><strong>Rationale:</strong> Adding new types requires no changes to existing code (Open/Closed Principle). A switch would grow unboundedly.</p>
</div>

Issue 番号の特定方法

1. ユーザーが直接指定した場合（例：/note-it #42）は、その番号を使用します
2. feat/issue-42-* または fix/issue-42-* という名前のブランチ上にいる場合は、42 を抽出します
3. 最後の /goal の対象が #42 だった場合は、42 を使用します
4. それ以外の場合は、ユーザーに「メモファイルにはどの Issue 番号を使用しますか？」と尋ねます

エッジケース

状況	対応
Issue 番号が見つからない	ユーザーに指定を求める
docs/ ディレクトリが存在しない	自動的に作成する
この Issue のメモファイルがすでに存在する	「既存のメモを更新しますか、それとも上書きしますか？」と尋ねる — デフォルトでは更新（新しい項目を追記）
仕様からの逸脱や未解決の質問がない	「None — 実装は記載された仕様に従っています。」と記載する
仕様／PRD ファイルが見つからない	Open Questions に「tasks/prd-*.md に PRD が見つかりませんでした — 元の要件と照らし合わせて確認してください。」と記載する

チェックリスト

保存する前に：

• Issue 番号を特定した
• 4 つすべてのカテゴリを確認した（一部が「None」の場合も含む）
• 設計上の判断で、実施内容だけでなく判断理由も説明している
• 仕様からの逸脱について、仕様と実装の違いを明確に示している
• トレードオフで、検討した具体的な代替案に触れている
• 未解決の質問が、ユーザーが「はい／いいえ」や方針を回答できる具体的な内容になっている
• HTML が適切に構成され、正しく表示される