chore: harden repository quality gates

docs/guides/README.md

@@ -7,3 +7,7 @@
 - [从零开始](../getting-started/)
 - [可复用流程](../playbooks/)
 - [参考清单](../references/)
+
+## 当前指南
+
+- [仓库维护与质量门禁](./仓库维护与质量门禁.md)

docs/guides/仓库维护与质量门禁.md

@@ -0,0 +1,64 @@
+# 仓库维护与质量门禁
+
+本文档是维护 `vibe-coding-cn` 的操作指南，用于保证目录迁移、文档更新、Skills 调整和工具配置变更后仍然可验证。
+
+## 必跑命令
+
+```bash
+make test
+```
+
+`make test` 当前会执行：
+
+1. `make lint`：使用 `.github/lint_config.json` 校验 Markdown。
+2. `make check-links`：使用 `scripts/check-local-links.py` 校验仓库内 Markdown 相对链接。
+
+## 单项检查
+
+```bash
+make lint
+make check-links
+git diff --check
+git submodule status --recursive
+find . -xtype l -print
+```
+
+验收标准：
+
+- `make lint` 无错误。
+- `make check-links` 输出 `OK local links checked`。
+- `git diff --check` 无输出。
+- `git submodule status --recursive` 能列出所有 submodule 指针。
+- `find . -xtype l -print` 无输出。
+
+## CI 规则
+
+GitHub Actions 的 CI 监听：
+
+- `push` 到 `develop` 或 `master`
+- `pull_request` 到 `develop` 或 `master`
+- 手动触发 `workflow_dispatch`
+
+CI 使用 Node.js 22 运行 `markdownlint-cli`，避免新版依赖在旧 Node.js 上因正则 `/v` flag 崩溃。
+
+## 大文件规则
+
+- 不提交二进制运行时、构建产物、缓存目录和生成数据。
+- 第三方仓库优先放在 `tools/external/`，完整仓库优先使用 Git submodule。
+- 工具生成物默认加入 `.gitignore`。
+- 如果确需保留大文件，必须在对应 README 中写明用途、来源、更新方式和替代方案。
+
+## 迁移检查
+
+目录迁移或重命名后，必须检查：
+
+1. `README.md`
+2. `AGENTS.md`
+3. `llms.txt`
+4. `llms-full.txt`
+5. `metadata/redirects.yml`
+6. 相关目录下的 `README.md` / `AGENTS.md`
+7. `.github/workflows/ci.yml`
+8. `.github/labeler.yml`
+
+旧路径只允许出现在 `CHANGELOG.md`、`metadata/redirects.yml` 或调试/迁移记录中。