← ClaudeAtlas

ai-repo-engineering-layoutlisted

给 AI 项目补「工程化分区」的可复用 SOP:tests/ vs tools/ 分界、models/ 模型台账、logs/ 默认不写盘、doc/learn/ 教学层、以及 src/→core/ 这类改名的裁决框架。同时含「AI 项目该往 README 放什么图 / 视频怎么链」的平台事实。触发词:项目目录不规范、是不是该有 core/log 目录、工程化分区、AI 项目结构、大模型管理放哪、学习中心、文档不友好、加 mermaid 图解、README 放演示视频。
xingtu1996/xingtu-skills · ★ 2 · AI & Automation · score 74
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**(`![](x.mp4)` 渲染成坏图,点 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_*` | 混住的真实代价**不是难看,是没人说得清哪些