祝融说。

38.1 阶段一：文档先行，建立约束层

项目背景：一个安全的、跨平台的、支持离线使用的笔记应用——"Guardian Notes"（教学重组案例：情节由真实项目的典型片段重组而成，数字为演示量级）。它集合了多种常见技术难题：

产品经理的原始需求："我们要做一款笔记应用，用户可以在上面写私密的日记、备忘录。我们最大的卖点是'安全'和'随处可用'：1. 绝对安全——用户的笔记内容必须在他们自己的设备上加密，就算服务器被黑，黑客也拿不到任何有意义的内容；2. 跨平台——必须能在 Web 浏览器、桌面应用（Windows, macOS）上使用；3. 离线优先——没网也能查看、创建和编辑笔记，有网后自动同步；4. 基本功能——支持 Markdown、按文件夹组织笔记。"

这个案例的"魔鬼之处"：跨平台（Web + Desktop）——处理不同运行环境的差异，是"环境约束"的绝佳演练场；离线优先（Offline-First）——在本地持久化数据并处理复杂的数据同步和冲突解决逻辑；端到端加密（E2EE）——极其严肃的安全需求，加密逻辑一旦出错后果是灾难性的。

技术栈：核心逻辑 TypeScript（一份代码多处运行）+ Web 端 React + 桌面端 Electron + 本地存储 IndexedDB（Dexie.js）+ 云端同步 RESTful API（简化）+ 加密库 libsodium-wrappers。

阶段一：文档先行，建立约束层。

目标：在编写任何一行应用代码之前，先用文档为 AI 和我们自己构建起坚不可摧的"思想护栏"。这是架构约束的集中体现。

行动：在项目根目录创建 CONTEXT.md，另在 .docs/ 创建三份配套文件，按第 12、13 章分工。下面保留案例三层设计，但把事实与约束分别落盘。

先创建 CONTEXT.md（项目蓝图）：

# Guardian Notes — CONTEXT
目标：安全、跨平台、离线可用的 Markdown 笔记，支持文件夹与恢复联网后同步。
技术栈：TypeScript、React、Electron、Dexie.js、RESTful API、libsodium-wrappers。
理由：复用核心逻辑，通过适配器隔离平台差异；本地存储支持离线工作。
三层事实：
1. Core Logic：平台无关的 TypeScript 业务与加密模块。
2. Platform Adapters：连接核心逻辑与 Web/Electron 运行环境。
3. UI Layer：消费适配器的 React 组件。
数据模型、API 契约和目录：调研后在本文件补齐并批准，不在宪法复制。
首个里程碑：加密模块接口与测试；后续为本地读写、平台集成及同步。
实施约束：[ARCHITECTURE.md](.docs/ARCHITECTURE.md)。
行为准则：[AGENTS.md](.docs/AGENTS.md)。

蓝图中的待定契约必须在对应实施前补齐；以上摘录不是跳过调研的许可。

① 创建 .docs/AGENTS.md（AI 行为准则）：

# AI Agent Directives: Project "Guardian Notes"
## Persona: Senior Security-Focused Engineer
You are to act as a Senior Software Engineer with a specialization in security.

## Reading and Enforcement:
1. Read [project facts and goals](../CONTEXT.md).
2. Read [implementation constraints](ARCHITECTURE.md) and cite applicable rule IDs.
3. Read [verified progress](CHANGELOG.md) before selecting the next task.
4. Report conflicts or unknown security assumptions before implementation.
5. Do not weaken constraints to obtain a passing result.

② 创建 .docs/ARCHITECTURE.md（架构宪法 + 负空间红线）：

# "Guardian Notes" - Architecture Document (v0.1)
## 1. Project Facts
See [CONTEXT.md](../CONTEXT.md) for goals, stack, three layers, models and contracts.
CONTEXT.md links back to .docs/ARCHITECTURE.md. Do not duplicate those facts here.

## 2. Red Lines and Review Triggers
- G1: Treat user-data changes as security-critical; review before implementation.
- G2: Do not break offline behavior or supported-platform compatibility.
- G3: Prefer simple auditable code; review complexity before adding abstractions.
- G4: Never treat the server as a trust anchor.
- G5: Do not disable TypeScript strict mode.

## 3. The "Forbidden Zone" (Negative Constraints) —— 负空间红线
- G6 — No Unencrypted Data on the Wire: 发送到服务器的任何数据都必须先加密。
- G7 — No Private Keys on the Server: 用户的主解密密钥绝不允许存在服务器上。
- G8 — Core Logic Cannot Access `window` or `document`: 核心逻辑必须平台无关。
- G9 — UI Components Cannot Perform Direct Data-Access: 所有数据操作必须通过 Core Logic。

③ 初始化 .docs/CHANGELOG.md（航行日志）：

# Changelog
## Unreleased
- Decision: Established the initial project structure and core architectural principles.
- Next Step: Begin implementation of the "Core Logic" layer, starting with the encryption module.

阶段复盘：我们花了大约一个小时，没有写任何一行应用代码，但取得的成果是决定性的——设定了基调（通过 AGENTS.md 让 AI 知道这是一个严肃的安全优先项目）、建立了骨架（通过 CONTEXT.md 记录三层事实与选型理由，用 ARCHITECTURE.md 单独约束跨层访问）、划定了红线（通过负空间约束提前封死最可能导致项目失败的"捷径"）、明确了起点（通过 CHANGELOG.md 清晰知道下一步该做什么）。

心法："慢就是快"——花在文档上的 1 小时，往往能为后续省下远超于此的返工时间（"1 小时省 10 小时"是量级比喻，非测量值）。"先想好不做什么"——负空间约束，比正面描述功能更能体现架构的智慧。

38.2 阶段二：核心流程，"三步走"强制执行

目标：实现项目的核心功能——笔记的本地加密、存储和读取。在这个过程中严格执"调研 → 谋局 → 落地"的流程约束，强制"慢思考"。

场景：实现 EncryptionService，负责生成密钥、加密和解密文本。

第一步：调研（Research）。不能直接让 AI 写代码，先让它当"研究助理"（在保存状态后的新会话中先读取蓝图与三份配套文档）：

[读取 CONTEXT.md、.docs/AGENTS.md、.docs/ARCHITECTURE.md、.docs/CHANGELOG.md] Acknowledge and internalize. Our next step is to implement the encryption module. Your Role: Act as the Senior Security-Focused Engineer defined in the agent directives. Task: We have decided to use libsodium-wrappers. Before we write code, conduct a brief research:

1. Key Derivation: What is the recommended function for deriving a strong encryption key from a user's password? What parameters (salt, ops-limit, mem-limit) are involved, and what are sane defaults?
2. Encryption/Decryption: What is the specific function for symmetric encryption using XChaCha20-Poly1305-IETF? What are the inputs (key, nonce, plaintext) and outputs? How should the nonce be generated and stored? Constraint: Do not provide a full implementation yet. Focus on background information and function signatures.

AI 会返回一份关于 crypto_pwhash（密钥派生）和 crypto_aead_xchacha20poly1305_ietf（加密）的、详尽的、带有安全警告的技术备忘录，解释"盐"（salt）和"随机数"（nonce）的重要性。

第二步：谋局（Strategizing）。基于研究结果，要求 AI 设计 EncryptionService 的"蓝图"（接口 + 实现策略注释 + 任务清单，没有方法体）：

Task: 1. Define the Interface: Propose a TypeScript interface named IEncryptionService that exposes methods for: generating a new master key, deriving a key from a password, encrypting a string, decrypting a ciphertext. 2. Plan the Implementation: For each method, write a short comment describing its implementation strategy based on your research. 3. Task Breakdown: Create a sequential task list. Constraint: Provide only the interface, comments, and task list. No method bodies yet.

这个"谋局"过程，迫使我们思考模块的"公共契约"，而不是过早陷入实现细节。

第三步：落地（Implementation）。所有思考和设计完成后，进入"高速编码"阶段，逐一完成任务清单里的任务，并让 AI 为每个方法编写单元测试、确保覆盖率达标（质量约束初步介入）。

阶段复盘：我们抵制住了"直接让 AI 写加密代码"的诱惑。通过"三步走"，将一个复杂的、安全敏感的任务分解成可控、可审查的多个小步骤。最终得到的代码不是 AI"一拍脑袋"想出来的，而是我们和 AI 基于共同研究和设计深思熟虑后的产物，其可靠性远高于"一步到位"式的生成。

38.3 阶段三：环境调试，遥测日志攻克平台差异

目标：将核心逻辑集成到 Web 和 Electron 两个不同的平台，解决"环境依赖型"问题。这是环境约束的实战。

场景：在 Electron 桌面端发现笔记的保存速度偶尔变得极慢，甚至导致应用卡死；但同样的操作在 Web 端非常流畅。代码是同一份（Core Logic），不同环境表现天差地别。

错误的流程：对 AI 说"我的 Electron 应用很卡，Web 上却不卡，为什么？"——这是一个无法回答的问题，AI 只能靠猜。

正确的流程（遥测驱动）：

1. 植入遥测探针：在 Core Logic 的"保存笔记"流程中植入详细的结构化日志，覆盖关键阶段：SAVE_NOTE_STARTED → ENCRYPTION_STARTED → ENCRYPTION_FINISHED（记录耗时）→ LOCAL_DB_WRITE_STARTED → LOCAL_DB_WRITE_FINISHED（记录耗时）→ SAVE_NOTE_FINISHED（记录总耗时），日志包含 trace_id、时间戳、note_id 等上下文；
2. 在真实环境中取证：在 Electron 应用中打开开发者工具，执行几次缓慢的"保存"操作，从控制台复制完整的、JSON 格式的结构化日志流；
3. 逆向投喂日志：把日志流投喂给 AI（角色：精通 Electron 和浏览器存储的性能工程师），并给出关键问题："同一操作在 Chrome 里 DB 写入只要 100ms，为什么 Electron 里 IndexedDB 写入慢 80 多倍？（它们用同一个 V8 引擎）";
4. AI 的精准诊断：日志清晰地显示 8.5 秒耗时 99% 花在 LOCAL_DB_WRITE 上（加密很快）。AI 的知识库中有大量关于 Electron 和 Web 性能差异的知识——Electron 主进程和渲染进程虽然都用 V8，但底层 I/O 模型和磁盘交互方式与沙箱化的浏览器环境有本质区别。它提出极具洞见的假设："Electron 中频繁小批量地向 IndexedDB（底层是文件系统）写入，可能受主进程 I/O 瓶颈或杀毒软件实时扫描影响。Chrome 浏览器对此有更深度的优化。常见解决方案是把多次小写入批处理为一次大写入。";
5. 修复与验证：根据 AI 建议，使用 Dexie.js 的 bulkPut() API，把多个保存操作缓存起来一次性写入数据库。再次运行——Electron 端保存速度恢复到与 Web 端一样的毫秒级。

阶段复盘：面对"黑盒"环境问题，我们没有陷入猜测。我们用"遥测"将问题"数据化"和"可视化"，利用 AI 渊博的跨领域知识库对数据做出精准解读，找到了那个隐藏在平台差异中的"魔鬼"。

38.4 阶段四：重构优化，测试守住底线

目标：核心功能完成后进行"净化"，移除技术债务、优化结构，同时确保没有破坏任何现有功能。这是质量约束和定期垃圾回收的实践。

场景：NoteService.ts 在多次迭代后变得臃肿，混杂了数据操作、加密调用和初步的同步逻辑。我们想让 AI 重构它，拆分成更内聚的多个模块。

行动：

1. 建立"防退化"基线：功能防线——为 NoteService.ts 的所有公共方法编写 100% 分支覆盖率的单元测试（运行一遍全部通过，作为"功能正确性基线"）；性能防线——为最关键的 saveNote 和 loadNotes 函数编写基准测试，记录平均执行时间（作为"性能基线"）；
2. 授权 AI 进行"戴着镣铐的舞蹈"——下发防退化契约：

Context: We need to refactor our NoteService.ts module. It has grown too large. Role: Senior Software Architect, obsessed with the Single Responsibility Principle (SRP). Task: 1. Propose a Refactoring Plan (split into NoteRepository.ts, SyncService.ts, etc.); 2. Execute after approval. ANTI-REGRESSION CONTRACT (ABSOLUTE & NON-NEGOTIABLE):

1. No Functional Regression: must pass all existing unit tests without modifying test files.
2. No Performance Regression: key operations must remain within 5% of baselines.
3. Clean Up: after refactoring, run ts-prune to remove now-unused helpers/imports.

3. AI 执行与自动化验收：AI 把 500 行的文件拆成 3 个 100 多行的新文件。验收三关：第一关单元测试（若有失败，把失败日志逆向投喂给 AI 自我修复）；第二关性能测试（若有退化，反馈给 AI 优化）；第三关垃圾回收（ts-prune 和 depcheck 清理死代码和孤儿依赖）。

阶段复盘：我们成功完成了一次复杂的、有风险的重构，但整个过程充满信心——信心不来自于对 AI 的"盲目信任"，而来自于我们建立的、自动化的、不可逾越的"质量电网"。重构的结果不仅是代码更清晰，我们还通过"垃圾回收"让代码库变得比重构前更小、更纯粹——实现了一次真正的"逆生长"。

【复盘】有效约束的完整闭环

Guardian Notes 案例展示了"有效约束"的完整闭环：架构约束定方向（文档先行）、流程约束控节奏（三步走）、环境约束长眼睛（遥测驱动）、质量约束守底线（测试电网）。四类约束像一个全方位"护城河"，确保 AI 这头巨兽始终在你规划好的安全航道内行进。