ai-repo-engineering-layoutlisted
Install: claude install-skill xingtu1996/xingtu-skills
# AI 项目工程化分区 SOP
## 何时用
需求信号:「目录感觉不太一样」「是不是该有 core / log 之类的分区」「这是 AI 项目,得有大模型管理」
「文档要更友好、更多、学习向」「加 mermaid 图解」「演示视频链到 README」。
**先判断**:这是**产品型**仓库(有可看产出)还是纯代码库?纯代码库不需要 demo/ 与学习中心。
---
## 0 · 四条平台事实(实测,别重复试错)
1. **GitHub 的 `<video>` 标签会被 Markdown 清洗器整个剥掉。**
复现:`gh api -X POST /markdown -f mode=gfm -f context=<owner>/<repo> -f text='<video controls src="a.mp4"></video>'`
→ 返回 `<p dir="auto"></p>`。⚠️ 该接口返回 **HTML 文本**,**不要加 `--jq`**。
2. **仓库里唯一「打开就动」的形态只有 GIF**(`` 渲染成坏图,点 mp4 只给下载按钮)。
→ README 的正确形态:**GIF 自动播 + 点图链到 mp4 文件页**;想"点一下就播带声音"只能靠**仓库自带的本地播放器** `demo/index.html`。
3. **GIF 自动播放不是无条件的**:读者开了「减少动态效果」会停在第一帧 → **首帧必须本身是合格封面**。
4. **GitHub 原生渲染 mermaid**(` ```mermaid ` 围栏)。本地 MD 阅读器不一定渲染 → 关键图**附一个纯文本折叠块兜底**(`<details>`)。
> `gh` 常不在沙箱 PATH → 用 `/opt/homebrew/bin/gh` 绝对路径。
---
## 1 · 分区判据(一句话:**这个目录里会不会红**)
| 会不会红 | 目录 | 说明 |
|---|---|---|
| **会红** | `tests/` | 可回归**判据**。纯标准库优先(守护不该有依赖);退出码要能用 |
| 会量 | `tools/` | 一次性**量具**:探针 / 基准 / 剖析 / 预览 |
| 讲道理 | `doc/` | 选型 / 决策 / 踩坑 |
| 会变的资产 | `prompts/` `models/` | 提示词 / 模型台账 —— **单独成目录,别混进代码** |
| 每次再生 | `cache/` `logs/` | gitignore,但**留一个 README 说明约定** |
**三个 AI 项目特有缺口**(普通项目没有,逐个补):
| 目录 | 补什么 | 关键约束 |
|---|---|---|
| `models/` | 模型**台账**:用哪个 / 换模型 SOP / 降级路径 / 红线 | ⚠️ **不存权重**(在 `~/.ollama/models`)。与代码里的 `models.py`(数据契约)同名不同层 → README 里显式澄清 |
| `logs/` | 运行日志 | **默认不写盘**。理由:日志会记输入路径/章节标题(与"内容不出本机"承诺有张力)、`.app` 的 Resources 理论只读、用户不会去删 |
| `tests/` | 从 `tools/` 分出 `verify_*` | 混住的真实代价**不是难看,是没人说得清哪些