feat: add agents-md.md and quickstart.md

Author: qorzj

docs/agent-skills.md

@@ -1,4 +1,4 @@
-# Deep Code CLI Agent Skills 指南
+# Agent Skills
 
 ## 概述
 

docs/agent-skills_en.md

@@ -1,4 +1,4 @@
-# Deep Code CLI Agent Skills Guide
+# Agent Skills
 
 ## Overview
 

docs/agents-md.md

@@ -0,0 +1,220 @@
+# AGENTS.md
+
+`AGENTS.md` 是写给 AI 编码助手的项目说明文件。它用于记录长期有效的项目规则，让 Deep Code 在这个仓库中工作时知道如何安装依赖、运行测试、修改代码、提交变更，以及遵守哪些团队约定。
+
+如果你经常在提示词里重复说明“先运行哪个测试”“不要修改哪个目录”“PR 描述要包含什么”，就适合把这些内容写进 `AGENTS.md`。
+
+## 适合写什么
+
+`AGENTS.md` 适合保存当前项目的稳定规则：
+
+- 项目结构和重要目录
+- 安装、开发、构建、测试命令
+- 代码风格、命名约定、格式化要求
+- 测试要求和验证步骤
+- 提交、PR、发布流程
+- 安全、配置、凭据处理注意事项
+- 只对本仓库有效的 AI 协作规则
+
+不适合写入 `AGENTS.md` 的内容：
+
+- 一次性任务要求，例如“这次只改登录页”
+- 复杂可复用工作流，此类内容更适合写成 Agent Skill
+- 外部系统连接信息，此类能力更适合通过 MCP 配置
+- API Key、密码、Token 等敏感信息
+
+## 创建文件
+
+在项目中运行：
+
+```text
+/init
+```
+
+Deep Code 会帮助你创建或更新 `AGENTS.md`。你也可以手动创建：
+
+```bash
+touch AGENTS.md
+```
+
+如果你希望把说明放在 Deep Code 专用目录中，也可以使用：
+
+```bash
+mkdir -p .deepcode
+touch .deepcode/AGENTS.md
+```
+
+常见选择：
+
+| 文件 | 适合场景 |
+| ---- | -------- |
+| `AGENTS.md` | 希望项目中的不同 AI 编码工具都能读取 |
+| `.deepcode/AGENTS.md` | 希望规则只面向 Deep Code |
+| `~/.deepcode/AGENTS.md` | 个人默认偏好，适用于没有项目说明的仓库 |
+
+## 推荐结构
+
+保持简短、清晰、可执行。推荐从下面这些章节开始：
+
+```markdown
+# 仓库指南
+
+## 项目结构
+
+说明主要目录，以及新增代码应该放在哪里。
+
+## 开发命令
+
+- `npm install` — 安装依赖。
+- `npm test` — 运行测试套件。
+- `npm run build` — 构建项目。
+
+## 代码风格
+
+说明格式化、命名和框架约定。
+
+## 测试
+
+说明什么时候需要添加测试，以及需要运行哪些命令。
+
+## Pull Request
+
+说明提交风格、PR 检查项、截图或发布说明要求。
+
+## AI 助手注意事项
+
+列出 AI 助手需要遵守的规则，例如不要修改哪些文件，或完成前要执行哪些检查。
+```
+
+你不需要保留所有章节。只写对当前项目有帮助的内容。
+
+## 写作原则
+
+### 写具体命令
+
+推荐：
+
+```markdown
+## 开发命令
+
+- `npm install` — 安装依赖。
+- `npm test` — 运行全部测试。
+- `npm run build` — 执行类型检查并构建 CLI。
+```
+
+避免：
+
+```markdown
+完成前运行常用命令。
+```
+
+### 写明确规则
+
+推荐：
+
+```markdown
+## 测试
+
+修改行为时需要新增或更新测试。完成前，测试相关修改运行
+`npm test`，代码修改运行 `npm run build`。
+```
+
+避免：
+
+```markdown
+确保一切正常。
+```
+
+### 写项目事实
+
+推荐：
+
+```markdown
+## 项目结构
+
+- `src/` 存放应用代码。
+- `tests/` 存放自动化测试。
+- `docs/` 存放面向用户的文档。
+```
+
+避免：
+
+```markdown
+这是一个普通的 TypeScript 项目。
+```
+
+### 写安全边界
+
+推荐：
+
+```markdown
+## 安全
+
+不要提交 API Key 或 Token。本地凭据放在 `~/.deepcode/settings.json`，
+项目示例中的敏感信息需要脱敏。
+```
+
+避免：
+
+```markdown
+注意保护密钥。
+```
+
+## 示例
+
+下面是一个较完整的 `AGENTS.md` 示例：
+
+```markdown
+# 仓库指南
+
+## 项目结构
+
+- `src/` 存放应用代码。
+- `src/tests/` 存放自动化测试。
+- `docs/` 存放面向用户的文档。
+- `config/` 存放项目配置示例。
+
+## 开发命令
+
+- `npm install` — 安装依赖。
+- `npm test` — 运行自动化测试。
+- `npm run build` — 运行检查并构建 CLI。
+
+## 代码风格
+
+使用 TypeScript。保持代码清晰，优先使用明确命名，并遵循现有
+格式风格。不要引入无关重构。
+
+## 测试
+
+修改行为时需要添加测试。优先运行范围最小的相关测试；条件允许时，
+完成前运行 `npm test` 或 `npm run build`。
+
+## AI 助手注意事项
+
+- 不要提交密钥或本地生成文件。
+- 保留用户已有修改。
+- 说明无法执行的验证步骤。
+```
+
+## 与 Skills、MCP 的区别
+
+| 工具 | 适合放什么 |
+| ---- | ---------- |
+| `AGENTS.md` | 当前仓库的长期规则、命令、风格、验证步骤 |
+| Agent Skill | 可复用工作流、领域知识、模板、脚本、参考资料 |
+| MCP | GitHub、浏览器、数据库等外部工具和实时数据 |
+
+常见组合：
+
+- 在 `AGENTS.md` 中写“这个项目怎么做”
+- 在 Agent Skill 中写“这类任务怎么做”
+- 用 MCP 提供“需要连接外部服务才能做”的能力
+
+## 维护建议
+
+- 项目命令变化后及时更新
+- 删除已经过期的规则
+- 避免写太长，优先保留高频、重要、容易出错的约定
+- 不要写敏感信息
+- 如果规则只适用于某次任务，直接写在当前对话中即可