宜博 / lemonboss

<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width,initial-scale=1" />
<title>阅读指南 · LemonBoss PRD</title>
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,300;9..144,500;9..144,700&family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet" />
<link rel="stylesheet" href="assets/shell.css" />
</head>
<body data-page="reading-guide.html">
<div class="shell">
  <aside id="sidebar"></aside>
  <main class="page">
    <header class="page-head">
      <div class="crumb"><span class="pill">00 · OVERVIEW</span><span class="sep">/</span><span>阅读指南</span></div>
      <h1>阅读指南</h1>
      <p class="deck">本套文档既是给人类决策的 PRD，也是给 Claude Code 的<b>可执行构建清单</b>。两类读者各有路径。</p>
    </header>
    <article class="body">

      <section>
        <h2>两个读者</h2>
        <div class="grid-2">
          <div class="card l3">
            <span class="tag L3">HUMAN</span>
            <h3>人类 · 决策 / 评审</h3>
            <p>关心「想做什么、为什么、值不值得」。阅读路径：</p>
            <ol style="padding-left:20px;color:var(--ink-soft)">
              <li><a href="index.html">封面</a></li>
              <li><a href="prd-background.html">背景</a> · <a href="prd-personas.html">角色</a></li>
              <li><a href="requirement.html">原始需求</a> · <a href="scope.html">范围与原则</a></li>
              <li><a href="prd-feature-tree.html">功能树</a> · <a href="prd-user-flows.html">用户流程</a></li>
              <li><a href="loops-overview.html">三层 Loop</a> · <a href="agents-overview.html">六个 Agent</a></li>
              <li><a href="plan-migration.html">最小改造路径</a> · <a href="plan-risks.html">风险</a></li>
            </ol>
            <p class="sig">预估 30 分钟。最后回到 <a href="plan-risks.html">plan-risks</a> 末尾回答 3 个 yes/no。</p>
          </div>

          <div class="card l1">
            <span class="tag L1">CLAUDE CODE</span>
            <h3>Agent · 执行 / 复现</h3>
            <p>关心「这个项目要落地什么文件、什么签名、什么行为」。阅读路径：</p>
            <ol style="padding-left:20px;color:var(--ink-soft)">
              <li>本页 — 学会怎么抽取结构化信息</li>
              <li><a href="prd-feature-tree.html">功能树</a> — 拿到所有 Unit id 与依赖关系</li>
              <li><a href="sdd-overview.html">SDD 总览</a> — 了解 MVCP 四象限</li>
              <li><a href="sdd-model.html">Model</a> · <a href="sdd-view.html">View</a> · <a href="sdd-control.html">Control</a> · <a href="sdd-process.html">Process</a> — 抽取构建清单</li>
              <li><a href="api-contracts.html">Unit Contract</a> — 跨 Unit 握手协议</li>
              <li><a href="plan-reproducibility.html">复现指南</a> — 执行 prompt</li>
            </ol>
            <p class="sig">机械化阅读，不需要欣赏 prose。所有 <code>data-*</code> 属性是 Agent 抓取的锚点。</p>
          </div>
        </div>
      </section>

      <section>
        <h2>HTML 锚点协议（Claude Code 读取）</h2>
        <p>所有结构化信息都通过 <code>data-*</code> 属性暴露。Agent 用 cheerio 选择器即可机械抽取，无需 NLP。</p>
        <table>
          <thead><tr><th>属性</th><th>出现位置</th><th>含义</th><th>选择器示例</th></tr></thead>
          <tbody>
            <tr><td><code>data-doc</code></td><td>顶级 <code>&lt;article&gt;</code></td><td>文档类型：prd / sdd</td><td><code>article[data-doc="prd"]</code></td></tr>
            <tr><td><code>data-rev</code></td><td>article / section</td><td>修订号，单调递增</td><td><code>section[data-rev="3"]</code></td></tr>
            <tr><td><code>data-unit-id</code></td><td>SDD section</td><td>本 section 描述的 Unit</td><td><code>section[data-unit-id="auth-be"]</code></td></tr>
            <tr><td><code>data-type</code></td><td>SDD section</td><td>Unit 类型：be / fe / mw / db</td><td><code>[data-type="be"]</code></td></tr>
            <tr><td><code>data-depends</code></td><td>SDD section</td><td>本 Unit 依赖的其他 Unit id（空格分隔）</td><td>—</td></tr>
            <tr><td><code>data-contract</code></td><td><code>&lt;pre&gt;</code></td><td>契约定义 (openapi / tsinterface)</td><td><code>pre[data-contract="openapi"]</code></td></tr>
            <tr><td><code>data-acceptance</code></td><td><code>&lt;ul&gt;</code></td><td>验收标准列表</td><td>—</td></tr>
            <tr><td><code>data-mvcp</code></td><td>本套文档 SDD section</td><td>所属 MVCP 象限</td><td><code>[data-mvcp="model"]</code></td></tr>
            <tr><td><code>data-origin</code></td><td>PRD section</td><td>本 section 来源（用户 + 时间）</td><td>—</td></tr>
            <tr><td><code>data-conflict</code></td><td>PRD <code>&lt;aside&gt;</code></td><td>与历史 section 矛盾的标记</td><td>—</td></tr>
            <tr><td><code>data-changelog</code></td><td>PRD <code>&lt;footer&gt;</code></td><td>修订日志区</td><td>—</td></tr>
          </tbody>
        </table>
      </section>

      <section>
        <h2>抽取示例 — units.json 怎么从 SDD 派生</h2>
        <pre class="code"><span class="c">// 给 Claude Code 的 cheerio 代码片段</span>
<span class="k">const</span> $ = cheerio.<span class="n">load</span>(sddHtml);
<span class="k">const</span> units = $(<span class="s">'section[data-unit-id]'</span>).<span class="n">map</span>((_, el) =&gt; (<span class="p">{</span>
  id:          $(el).<span class="n">attr</span>(<span class="s">'data-unit-id'</span>),
  type:        $(el).<span class="n">attr</span>(<span class="s">'data-type'</span>),
  depends_on:  ($(el).<span class="n">attr</span>(<span class="s">'data-depends'</span>) || <span class="s">''</span>).<span class="n">split</span>(<span class="s">/\s+/</span>).<span class="n">filter</span>(Boolean),
  contract:    $(el).<span class="n">find</span>(<span class="s">'pre[data-contract]'</span>).<span class="n">text</span>(),
  acceptance:  $(el).<span class="n">find</span>(<span class="s">'ul[data-acceptance] li'</span>).<span class="n">map</span>((_,li)=&gt;$(li).<span class="n">text</span>()).<span class="n">get</span>(),
<span class="p">}</span>)).<span class="n">get</span>();
<span class="c">// → 直接落盘为 units.json 的 .units 字段</span></pre>
      </section>

      <section>
        <h2>MVCP 抽取约定</h2>
        <p>SDD 四象限页（<a href="sdd-model.html">Model</a> / <a href="sdd-view.html">View</a> / <a href="sdd-control.html">Control</a> / <a href="sdd-process.html">Process</a>）使用统一的 5 字段结构。每个定义都带：</p>
        <table class="dense">
          <thead><tr><th>字段</th><th>含义</th><th>示例</th></tr></thead>
          <tbody>
            <tr><td><b>name</b></td><td>唯一标识符</td><td><code>units.json</code> · <code>DevLoopDashboard</code> · <code>LoopController.runProject</code></td></tr>
            <tr><td><b>path</b></td><td>预期落盘路径</td><td><code>server/services/doc-store.js</code></td></tr>
            <tr><td><b>shape</b></td><td>结构定义（TS / TypeBox / Vue props）</td><td>代码块</td></tr>
            <tr><td><b>contract</b></td><td>行为契约（前置 / 后置条件）</td><td>列表</td></tr>
            <tr><td><b>tests</b></td><td>验收用例</td><td>列表</td></tr>
          </tbody>
        </table>
        <p>Claude Code 把 SDD 转成 Unit 任务时，每一条 MVCP 定义都可以独立映射到一个 Unit（或多个 Unit 共享）。</p>
      </section>

      <section>
        <h2>文档作为「构建清单」</h2>
        <p>把整套 PRD + SDD 看作一个机器可解析的 build manifest。复现流程：</p>
        <svg viewBox="0 0 1100 200" width="100%" role="img">
          <defs><marker id="arrG" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 Z" fill="#0E0E10"/></marker></defs>
          <g font-family="JetBrains Mono" font-size="11" fill="#0E0E10">
            <rect x="20"   y="70" width="160" height="60" rx="6" fill="#ECE4FB" stroke="#6E48C3"/>
            <text x="100" y="95" text-anchor="middle" font-weight="700">PRD HTML</text>
            <text x="100" y="113" text-anchor="middle" font-size="10">含 data-* 锚点</text>

            <rect x="220" y="70" width="160" height="60" rx="6" fill="#fff" stroke="#0E0E10"/>
            <text x="300" y="95" text-anchor="middle" font-weight="700">SDD HTML (MVCP)</text>
            <text x="300" y="113" text-anchor="middle" font-size="10">含 data-mvcp 锚点</text>

            <rect x="420" y="70" width="160" height="60" rx="6" fill="#F7E8D2" stroke="#C77C2C"/>
            <text x="500" y="95" text-anchor="middle" font-weight="700">cheerio 抽取</text>
            <text x="500" y="113" text-anchor="middle" font-size="10">→ build-manifest.json</text>

            <rect x="620" y="70" width="160" height="60" rx="6" fill="#E2F2EA" stroke="#0E8C5A"/>
            <text x="700" y="95" text-anchor="middle" font-weight="700">Architect Agent</text>
            <text x="700" y="113" text-anchor="middle" font-size="10">→ units.json</text>

            <rect x="820" y="70" width="160" height="60" rx="6" fill="#E2F2EA" stroke="#0E8C5A"/>
            <text x="900" y="95" text-anchor="middle" font-weight="700">LoopController</text>
            <text x="900" y="113" text-anchor="middle" font-size="10">→ 代码 + 测试</text>

            <g stroke="#0E0E10" fill="none" marker-end="url(#arrG)">
              <line x1="180" y1="100" x2="215" y2="100"/>
              <line x1="380" y1="100" x2="415" y2="100"/>
              <line x1="580" y1="100" x2="615" y2="100"/>
              <line x1="780" y1="100" x2="815" y2="100"/>
            </g>
          </g>
        </svg>
        <p>具体的 prompt 模板见 <a href="plan-reproducibility.html">plan-reproducibility</a>。</p>
      </section>

      <section>
        <h2>本文档版本</h2>
        <table class="dense">
          <thead><tr><th>rev</th><th>日期</th><th>变更摘要</th></tr></thead>
          <tbody>
            <tr><td>v0.1</td><td>2026-05-12</td><td>初版 24 页 · 单 HTML + 拆 24 页</td></tr>
            <tr><td>v0.2</td><td>2026-05-13</td><td>升级到 41 页：新增 PRD 标准章节、SDD MVCP 五页、原型补全、复现指南</td></tr>
          </tbody>
        </table>
      </section>

    </article>
    <nav class="prev-next"></nav>
    <footer class="site"><div><b>Section</b>00 · Overview</div><div><b>Page</b>reading-guide.html</div></footer>
  </main>
</div>
<script src="assets/shell.js"></script>
</body>
</html>