微信小程序协作规范

来源：亲子成长记施工包 AGENTS.md 的通用规范部分，已剥离该项目专属的 MVP 范围 / 文档索引，成为可复用的协作基线。

这是什么

AI 写代码很容易"行为失控"：擅自重构、硬编码密钥、跳过阶段。本技能在每次新对话开始时，给 AI 一套强制规范，把这类坑提前堵死；并可生成一份项目级 AGENTS.md，让 AI 每次开工先读。还能用 --check 扫描现有工程是否违规。

脚本自带 --self-test：生成规范后回读校验「5 大原则 + 安全边界」齐全，证明可用。

何时使用

用户说："开始微信小程序开发" / "帮我定 AI 协作规范" / "给 AI 定工作规范"
新建任何需要 AI 协助编码的项目，想把协作规则固定下来
想生成一份 AGENTS.md 放进项目根目录
想检查现有工程是否踩了安全红线（硬编码密钥 / .env 入库）

强制规范（AI 必须遵守）

1. 安全第一

禁止在代码 / 日志 / 提交记录出现密码、Token、API Key 明文
敏感信息只允许在配置文件或环境变量，且不在对话中展示具体值
涉及删除、重置、覆盖等不可逆操作，必须先向用户确认

2. 稳定优先

优先小步可验证改动，避免大范围重构
修改前说明影响范围，修改后说明验证结果
不破坏已在运行的功能

3. 沟通规范

全程简体中文沟通
不主动展示代码细节，除非用户要求
每次完成汇报：做了什么 / 为什么 / 用户能感受到什么变化

4. 最小改动原则

只改与当前任务直接相关的代码
不顺手重构 / 优化 / 加功能
有额外发现先汇报，由用户决定

5. 引用同步强制规则（P0，与安全同级）

凡改动涉及文件增删改、模块/函数/接口路径变更，必须立即全局搜索旧名，更新所有引用处
每日收口时再次检查当日此类改动是否同步

安全边界（最高优先级，任何角色不得违反）

[禁止] 不能直接删除文件 —— 删除前必须列路径等用户确认
[禁止] 不能修改 .env 等配置文件 —— 敏感配置禁止自动改动
[禁止] 不能在代码写明文密码 / Key —— 安全红线，发现须指出并拒绝
[禁止] 不能自动提交 Git —— 提交前须展示 commit message 等确认
[禁止] 涉及支付 —— 须完整测试，不允许在生产直接测试
[禁止] 个人信息保护 —— 用户数据不得明文存储，须有合规隐私处理

代码质量 / 敏感信息 / 进度管理（通用约定）

文档语言中文；错误处理保留完整日志，不静默吞异常
.env 内容绝不发给 AI；密钥只存 .env，讨论配置只说字段名
每次收口更新 progress.md（今天做了 / 明天计划 / 待决策）；新对话先读 progress.md 复述状态

分包独立开发强化（教备神器工具模块实践沉淀）

以下为从「教备神器」小程序工具模块真实协作规范反哺的增强项，叠加在上方通用基线之上，专治分包/多板块/Canvas 类项目的失控。

1. 命名隔离铁律（双板块/多分包场景）

物理 + 命名双层隔离：从源目录复制出独立分包后，所有标识符加统一前缀（如 zt- / ZT_），源文件绝不改。
标识符映射：全局常量 ZT_、变量 zt、顶级函数 ztXxx、HTML id ztXxx、localStorage key zitie_。
不影响项：Canvas 内部尺寸、A4 规格、颜色映射、绘制引擎核心逻辑（通用，不需前缀）。
AI 自查：当前操作的板块/分包是哪个？是否误用了其他板块的名称、文件、变量、函数？

2. 六大模板 P0 锁定（最高优先级）

已定版的核心模板（如 6 个课业用纸模板）任何修改必须先征得用户明确同意，违者立即回滚。
锁定范围：模板预览主文件、校/机构版元素配置 JSON、网格参数配置、相关 JS/CSS/HTML、页码检测与生成逻辑。
禁止：增删改元素、调样式参数（位置/颜色/字体/尺寸）、改页码/绘制/切换逻辑、加功能或删功能——除非用户明确授权（"可以改"/"确认"）。

3. 三层文档追溯（收口总结强制）

每次收口问：今日代码改动是否已在「产品规格文档」与「技术方案文档」中反映？ 遗漏立即补。
文档权威等级：多文档冲突时以权威文档为准，不得自行裁决后静默处理；发现矛盾立即汇报用户。
文档不动原则：只允许既定文档集，禁止 AI 自动创建额外文档（临时信息写入对应章节）。

4. Canvas 专项约束（小程序 Canvas 开发）

开发前检查：内部尺寸固定 1240×1754（A4 150dpi）；CSS 缩放用 canvas.style.width/height 而非改 canvas.width/height；绘制函数须能在 preview.html 与小程序 .js 间直接复制。
常见坑：文字模糊 → 先 ctx.font='48px serif' 且 canvas.width=cssW*dpr；线不直 → lineWidth 偶数 + 坐标整数；导出空白 → 绘制前先赋值 canvas.width/height；文字偏移 → 手动 ctx.textBaseline='middle'。
绘制顺序（不可颠倒）：背景 → 页眉 → 网格 → 文字（最上层）→ 导出。
字体缺失：用系统回退 serif 继续开发，不卡进度；字体就绪后替换回指定字体。

脚本用法

# 0) 先证明生成的规范齐全（推荐第一次用前跑一次）
python gen_agents.py --self-test

# 1) 生成项目级 AGENTS.md
python gen_agents.py \
  --project "亲子成长记" \
  --type "微信小程序" \
  --role partner \
  --out AGENTS.md

# 2) 检查现有工程是否违规（硬编码密钥 / .env 入库 / AGENTS 覆盖度）
python gen_agents.py --check <项目目录>

脚本把上述通用规范 + 你填的项目信息，渲染成标准 AGENTS.md，可直接放进项目根目录让 AI 每次读取。

注意事项

本技能提供通用基线。项目专属的 MVP 范围、接口清单、文档索引应放在独立的 AI要怎么做.md / AI开发路径.md 中，不要写进 AGENTS.md（避免规范被需求污染）。
技术栈默认按微信小程序 + FastAPI + 数据库给出约定；换栈时同步更新"技术栈专属约定"段。
规范再好也要人监督——配合 ai-work-acceptance 技能在每次交付后做验收。

shuangying0001-beep/wechat-miniprogram-devrules

wechat-miniprogram-devrules 是什么？

在你喜欢的 AI 中提问

文档