# AI Project Scaffold > 为 AI 模型项目创建标准化目录结构：覆盖数据→分词→模型→实验全链路，支持多方案并行、来源追踪、质量记录。内置健康检查、追踪链、实验对比、checkpoint管理。严格文档规范防止 AI 生成冗余文档。 - Skill: `lord1egypt/ai-project-scaffold` (Agent Skill) - Install (CLI): `npx skillmds@latest add lord1egypt/ai-project-scaffold` - Raw SKILL.md: https://api.skillmd.com/api/skills/lord1egypt/ai-project-scaffold/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Lord1Egypt (https://skillmd.com/u/lord1egypt) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/lord1egypt/ai-project-scaffold --- # AI 项目目录结构管理 v2.0 适用于涉及数据清洗、分词/Tokenization、模型训练、后训练、强化学习等完整 AI 管线的项目。 ## 🔴 文档铁律（AI 助手必须遵守） > ⚠️ 这是本 skill 最重要的部分。违反任何一条都应被视为严重错误。 ### 原则 1. **表 > 文** — 能用表格记录的，不写段落。表格可扫描、可对比、不冗余。 2. **记录决策，不写教程** — 文档回答"做了什么选择、为什么"，不写"怎么用、是什么"。 3. **一处一真理** — 同一信息绝不出现在两个文件里。信息有且仅有一个权威位置。 4. **日志即文档** — `experiment_log.md` 是唯一持续增长的文档。其他 README 只在结构变化时更新。 5. **写完删一半** — 写完任何文档后，删掉至少一半字数。留下的才是精华。 ### 禁止清单 | ❌ 绝对禁止 | ✅ 应该做 | |-------------|----------| | 写超过 200 字的段落说明 | 用表格或列表，每行 ≤ 一行 | | 在 README 里粘贴代码 | 代码放在 scripts/，README 只写脚本名+用途 | | 创建 `GUIDE.md`、`TUTORIAL.md`、`NOTES.md` 等随意命名的文档 | 只使用约定文件名 | | 重复其他文件已有的信息 | 用链接引用（如 `详见 01_data/README.md`） | | 自动生成"项目概述""背景介绍"等水字数的章节 | 空着也比写废话强 | | 写 `detailed_explanation_v2_final.md` | 一个主题一个文件，版本在文件名里（如 `token_eval_v2.md`） | | 用 `final`、`new`、`latest` 等模糊后缀 | 用数字版本号 v1, v2, v3 | ### 文档命名规范 ``` ✅ 好命名: architecture_decision_001_transformer.md # ADR 风格 qc_report_wikipedia_zh_2024-03-15.md # 数据集_日期 eval_benchmark_mmlu_v2.md # 主题_版本 ❌ 坏命名: notes.md # 太模糊 final_report.md # 哪个 final？ test.md # 测什么？ new_doc_v3_final_revised.md # 💀 ``` ### 允许的文档类型及字数上限 | 文档 | 最大字数 | 更新频率 | 说明 | |------|---------|---------|------| | 各层 `README.md` | 300 字 | 结构变化时 | 表格为主，不写段落 | | `experiment_log.md` | 不限（按条目追加） | 每次实验 | 唯一允许持续增长的文件 | | `metadata.yaml` | 不限 | 数据源变更时 | 结构化数据，不是散文 | | `eval.md`（分词方案下） | 500 字 | 评估完成后 | 表格 + 关键数字 | | `architecture_decision_*.md` | 500 字 | 做决策时 | 背景+选项+决策+后果 | | `qc_report_*.md` | 300 字 | 每次 QC | 数据集+问题+处理+结果 | | `meeting_*.md` | 200 字 | 每次会议 | 日期+议题+结论，不要流水账 | 超过字数上限的文档应拆分为多个文件，或用表格代替段落。 --- ## 设计理念 1. **分层管理** — 数据层 / 分词层 / 模型层 各自独立，互不污染 2. **多方案并行** — 每层支持多种技术方案/尝试并存，各自有独立空间 3. **来源可追溯** — 数据从哪来、经过什么处理、用到了哪个模型，全程可追踪 4. **质量可见** — 数据质量、分词效果、模型评估都有独立的记录空间 5. **文档极简** — 遵循上方🔴铁律，拒绝 AI 生成冗余文档 --- ## 目录结构 ``` / ├── README.md # 项目总览（≤300字） ├── _project_config.yaml # 项目元信息 ├── .gitignore # 自动生成，忽略 checkpoints/logs/数据/.env ├── scripts/ # 管理脚本（自动复制） │ ├── check_project.py # 健康检查 │ ├── trace.py # 追踪链生成 │ ├── compare_runs.py # 实验对比 │ └── checkpoint_mgmt.py # Checkpoint 管理 │ ├── 01_data/ # 📊 数据层 │ ├── README.md # 数据来源登记表（表格，≤300字） │ ├── 01_raw/ # 原始数据（按来源分目录） │ │ └── source_/ │ │ ├── metadata.yaml # 结构化元信息 │ │ └── data/ │ ├── 02_qc/ # 质量控制 │ │ ├── scripts/ # QC 脚本 │ │ ├── reports/ # QC 报告（命名: qc_report__YYYY-MM-DD.md） │ │ └── cleaned/ # 清洗后数据 │ ├── 03_processed/ # 处理后 │ │ ├── text/ │ │ ├── image/ │ │ ├── audio/ │ │ └── multimodal/ # 多模态细化 │ │ ├── image_text/ │ │ ├── video_text/ │ │ ├── audio_text/ │ │ └── interleaved/ │ └── 04_quality_log.md # 数据质量追踪日志（表格追加） │ ├── 02_tokenization/ # 🔤 分词层 │ ├── README.md # 分词策略总览（表格，≤300字） │ ├── 01_existing/ # 现成 tokenizer │ │ └── / │ │ ├── config.yaml │ │ └── notes.md # 选用理由（≤150字） │ ├── 02_custom/ # 自制 │ │ └── / │ │ ├── README.md # 方案说明（≤200字） │ │ ├── scripts/ │ │ ├── configs/ │ │ ├── vocab_output/ │ │ └── eval.md # 评估结果（表格，≤500字） │ ├── 03_training/ # token 相关训练 │ ├── 04_evaluation/ # 内在 + 下游评估 │ │ ├── intrinsic/ │ │ └── extrinsic/ │ └── 05_generated/ # 分词产生的新数据记录 │ ├── 03_models/ # 🧠 模型层 │ ├── README.md # 架构选型决策（表格，≤300字） │ ├── 01_pretraining/ │ │ └── // │ │ ├── configs/ # 训练配置 │ │ ├── scripts/ # 训练脚本 │ │ ├── checkpoints/ # gitignored │ │ ├── logs/ # gitignored │ │ └── eval/ │ ├── 02_post_training/ │ │ ├── sft/ # 监督微调 │ │ ├── dpo/ # DPO │ │ ├── orpo/ # ORPO │ │ ├── kto/ # KTO │ │ ├── simpo/ # SimPO │ │ └── rlhf/ # RLHF 流程 │ ├── 03_rl/ │ │ ├── ppo/ │ │ ├── grpo/ │ │ └── reward_models/ │ ├── 04_evaluation/ │ │ ├── benchmarks/ │ │ └── reports/ │ └── 05_deployment/ │ ├── 04_experiments/ # 🔬 实验管理 │ ├── experiment_log.md # 时间线日志（唯一可无限增长的文件） │ └── runs/ │ ├── 05_docs/ # 📚 文档（严格遵守铁律） │ ├── design/ # 架构决策记录（ADR 风格） │ ├── meetings/ # 会议记录（命名: meeting_YYYY-MM-DD_主题.md） │ └── references/ # 外部参考文献 │ └── 06_shared/ # 🔧 共享资源 ├── scripts/ # 通用脚本 └── configs/ ├── training/ # DeepSpeed/LoRA/QLoRA/WandB 模板 ├── data/ # 数据处理配置模板 └── deployment/ # 部署配置模板 ``` --- ## 🛠 管理工具 ### 新建项目 ```bash python3 init_ai_project.py --name "MyLLM" [--output /path/to/parent] ``` 自动生成：完整目录 + 各层 README 模板 + `.gitignore` + 5 个配置模板 + 管理脚本副本 ### 添加组件 ```bash # 数据来源（自动生成 metadata.yaml） --add-source --source <名称> # 分词方案（自动创建 scripts/configs/vocab/eval） --add-tokenizer --approach <方案名> # 预训练运行 --add-training --arch <架构> --run <运行名> # 后训练运行 --add-posttrain --method --run <运行名> # RL 运行 --add-rl --method --run <运行名> ``` ### 升级已有项目 ```bash python3 init_ai_project.py --name "MyLLM" --upgrade # 补充缺失目录 + .gitignore + 配置模板 + 管理脚本 ``` ### 健康检查 ```bash python3 check_project.py --name "MyLLM" # 扫描: 目录完整度 / metadata 字段 / eval 是否填写 / 日志是否更新 # 输出: 健康评分 0-100 + 具体问题清单 ``` ### 追踪链 ```bash python3 trace.py --name "MyLLM" # 全局追踪 python3 trace.py --name "MyLLM" --layer models # 只看模型层 python3 trace.py --name "MyLLM" --full # 含文件详情 ``` ### 实验对比 ```bash python3 compare_runs.py --name "MyLLM" # 全部对比 python3 compare_runs.py --name "MyLLM" --arch llama3 # 指定架构 python3 compare_runs.py --name "MyLLM" --stage post_training # 只看后训练 ``` ### Checkpoint 管理 ```bash python3 checkpoint_mgmt.py --name "MyLLM" list # 列出所有 python3 checkpoint_mgmt.py --name "MyLLM" clean --keep 3 --dry-run # 预览清理 python3 checkpoint_mgmt.py --name "MyLLM" clean --keep 3 # 每运行保留3个最新 python3 checkpoint_mgmt.py --name "MyLLM" archive --to /backup/ # 归档 python3 checkpoint_mgmt.py --name "MyLLM" stats # 磁盘统计 ``` --- ## 命名规范 | 层级 | 目录命名 | 示例 | |------|---------|------| | 数据来源 | `source_<描述>` | `source_wikipedia_zh`, `source_internal_docs` | | QC 报告 | `qc_report__YYYY-MM-DD.md` | `qc_report_wikipedia_2024-03-15.md` | | 分词方案 | `<方法>_v<版本>` | `bpe_v1`, `unigram_v2`, `sentencepiece_v1` | | 模型架构 | `<架构名>` | `llama3`, `qwen2`, `custom_moe` | | 训练运行 | `<描述>_v<版本>` | `baseline_v1`, `lr_3e4_v2`, `wd_0.1_v1` | | 后训练方法 | `<缩写>` | `sft`, `dpo`, `ppo`, `grpo` | | 会议记录 | `meeting_YYYY-MM-DD_<主题>.md` | `meeting_2024-03-15_arch_review.md` | | 设计决策 | `architecture_decision_<序号>_<主题>.md` | `architecture_decision_001_transformer.md` | --- ## 追踪链 每个阶段记录输入/输出依赖，形成完整链路： ``` source_wikipedia_zh (01_data/01_raw/) → qc_report_wikipedia_2024-03-15.md (01_data/02_qc/reports/) → bpe_v1 (02_tokenization/02_custom/) → eval.md 评估通过 → llama3/baseline_v1 (03_models/01_pretraining/) → sft/chat_v1 (03_models/02_post_training/) → ppo/reward_v2 (03_models/03_rl/) ``` > 💡 运行 `python3 scripts/trace.py --name <项目>` 自动生成追踪链。 --- ## AI 助手行为准则 使用本 skill 时，AI 助手必须: 1. **初始化项目时** — 只生成模板骨架，不填充假数据。空表格比假数据好。 2. **写 README 时** — 表格 > 列表 > 段落。默认用表格。 3. **记录实验时** — 追加到 `experiment_log.md`，用模板格式，不要新建文件。 4. **写评估报告时** — 数字和表格是主角，文字只是表头。 5. **不要做的事**: - ❌ 不要创建 `05_docs/` 下的随意命名的 `.md` 文件 - ❌ 不要在多个 README 里重复同一段话 - ❌ 不要写"本项目旨在..."这种水字数开头 - ❌ 不要生成超过 300 字的 README - ❌ 不要用 `final`、`new`、`latest`、`updated` 命名文件