docs: 将项目规范迁至 AGENTS.md 并保留 Claude 兼容入口

.claude/skills/deep-review/SKILL.md

@@ -44,7 +44,7 @@ argument-hint: "[PR number, PR URL, or empty for local changes]"
 使用 TeamCreate 创建审查团队，启动 **3 个并行 agent**，每个专注一个维度。
 
 给每个 agent 的共同上下文：
-- CLAUDE.md 的内容（项目架构、模式、技术栈）
+- AGENTS.md 的内容（项目架构、模式、技术栈；其他仓库若没有该文件，读取 CLAUDE.md 及其导入内容）
 - 完整的 diff 内容
 - 变更涉及的文件列表
 
@@ -69,7 +69,7 @@ argument-hint: "[PR number, PR URL, or empty for local changes]"
 ### Agent 3: 🏗️ 架构与质量审查 (architecture-reviewer)
 
 检查项：
-- 是否符合 CLAUDE.md 中描述的项目模式（ESM `.js` 后缀、单例模式、两阶段消息等）
+- 是否符合 AGENTS.md 中描述的项目模式（ESM `.js` 后缀、单例模式、两阶段消息等）
 - TypeScript 类型安全（不安全的 `any`、错误的泛型、async/await 陷阱）
 - 模块边界是否清晰，是否有循环依赖
 - 命名一致性、代码组织

.claude/skills/doc-health/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doc-health
-description: "Set up or audit documentation health for any repo. Use 'init' to bootstrap a docs/ structure (plans/, design/, research/) with YAML front matter, agent discovery scripts, and anti-rot mechanisms. Use 'audit' to detect stale design docs, undistilled completed plans, broken internal links, and CLAUDE.md drift. Use when: 'set up docs', 'doc health', 'check documentation', 'audit docs', 'bootstrap documentation', 'prevent doc rot'."
+description: "Set up or audit documentation health for any repo. Use 'init' to bootstrap a docs/ structure (plans/, design/, research/) with YAML front matter, agent discovery scripts, and anti-rot mechanisms. Use 'audit' to detect stale design docs, undistilled completed plans, broken internal links, and AGENTS.md drift. Use when: 'set up docs', 'doc health', 'check documentation', 'audit docs', 'bootstrap documentation', 'prevent doc rot'."
 argument-hint: "<init | audit>"
 ---
 
@@ -26,7 +26,7 @@ Bootstrap a documentation structure. Idempotent — skips anything that already
 - Identify the main source directory: check `src/`, `lib/`, `app/`, or project root for code directories
 - List top-level module directories (e.g., `src/auth/`, `src/api/`, `src/utils/`)
 - Check which of these already exist: `docs/`, `docs/plans/`, `docs/design/`, `docs/research/`
-- Check if `CLAUDE.md` exists and whether it already has a documentation section
+- Check if `AGENTS.md` exists and whether it already has a documentation section
 - Check if `scripts/docs-list.mjs` exists
 - Note the current date for `last_updated` fields
 
@@ -57,7 +57,7 @@ last_updated: "<today>"
 > TODO: Describe current architecture and key design decisions when next modifying this module.
 ```
 
-**How to infer the summary**: Read the module's `index.ts` (or main file) exports, or check README/CLAUDE.md for mentions. If nothing is available, use the directory name as-is.
+**How to infer the summary**: Read the module's `index.ts` (or main file) exports, or check README/AGENTS.md for mentions. If nothing is available, use the directory name as-is.
 
 ### Step 4: Create scripts/docs-list.mjs
 
@@ -170,9 +170,11 @@ if (jsonOutput) {
 }
 ```
 
-### Step 5: Update CLAUDE.md
+### Step 5: Update AGENTS.md
 
-If CLAUDE.md does not exist, create it with a minimal project header and the documentation section below. If it exists but has no documentation section, **append** the section. If a documentation section already exists, **skip**.
+If AGENTS.md does not exist, create it with a minimal project header and the documentation section below. If it exists but has no documentation section, **append** the section. If a documentation section already exists, **skip**.
+
+If a repository still keeps its guidance in `CLAUDE.md`, read that guidance first and preserve it when establishing `AGENTS.md` as the source of truth. Keep a `CLAUDE.md` containing `@AGENTS.md` when its Claude Code / Agent SDK consumers need compatibility. Never append project documentation to an import-only stub or maintain duplicate guidance in both files.
 
 Detect an existing section by searching for headings containing "Documentation", "Docs", or the Chinese equivalent.
 
@@ -235,7 +237,7 @@ Doc Health Init Complete:
   [created] docs/design/api.md (stub)
   [skipped] docs/design/utils.md (already exists)
   [created] scripts/docs-list.mjs
-  [updated] CLAUDE.md (appended Documentation section)
+  [updated] AGENTS.md (appended Documentation section)
 
 Next steps:
   - Fill in design doc stubs when working on each module
@@ -285,11 +287,11 @@ Scan all `.md` files in `docs/` for:
 - Code path references in backticks like `` `src/module/file.ts` `` — verify the file exists using Glob
 - Skip external URLs (http/https), anchors (#), and mailto links
 
-### Check 5: CLAUDE.md Module Drift
+### Check 5: AGENTS.md Module Drift
 
-If CLAUDE.md exists and lists module descriptions (look for file paths like `src/*/`):
+If AGENTS.md exists and lists module descriptions (look for file paths like `src/*/`):
 - Check that every listed path still exists on disk
-- Check that major source directories have at least a mention in CLAUDE.md
+- Check that major source directories have at least a mention in AGENTS.md
 - Report unlisted modules and phantom references
 
 ### Report
@@ -311,16 +313,16 @@ Aggregate all findings into a structured report:
 ### Broken Internal Links (N found)
 - docs/design/X.md:15 — references `src/old/file.ts` which does not exist
 
-### CLAUDE.md Drift (N found)
-- CLAUDE.md mentions `src/routing/` but directory does not exist
-- `src/cron/` exists but is not mentioned in CLAUDE.md
+### AGENTS.md Drift (N found)
+- AGENTS.md mentions `src/routing/` but directory does not exist
+- `src/cron/` exists but is not mentioned in AGENTS.md
 
 ### Summary
 - N stale design docs
 - N undistilled plans
 - N stale plans
 - N broken links
-- N CLAUDE.md drift issues
+- N AGENTS.md drift issues
 ```
 
 If everything is clean, output: "Doc health: all clear."

.claude/skills/setup-claude/SKILL.md

@@ -340,7 +340,7 @@ Use `gh pr diff` for the full diff, `gh pr view` for PR intent.
 Use TeamCreate to create a review team with **3 parallel agents**, each focused on one dimension.
 
 Shared context for all agents:
-- Content of CLAUDE.md (if it exists — read it first and include it if present)
+- Content of AGENTS.md (read it first if present; otherwise read CLAUDE.md and its imports)
 - Full diff content
 - List of changed files
 
@@ -365,7 +365,7 @@ Checks:
 ### Agent 3: Architecture & Quality Reviewer (architecture-reviewer)
 
 Checks:
-- If CLAUDE.md exists, verify changes follow the project patterns described there
+- Verify changes follow the project patterns in AGENTS.md, or CLAUDE.md and its imports in legacy repositories
 - Check project conventions: consistent import style, module patterns, code organization
 - Language-specific: type safety, idiomatic patterns, proper use of language features
 - Clean module boundaries, no circular dependencies
@@ -500,7 +500,7 @@ jobs:
 
             ## Step 2: Setup
 
-            1. Read CLAUDE.md if it exists to understand the project architecture and conventions.
+            1. Read AGENTS.md if it exists to understand the project architecture and conventions; otherwise read CLAUDE.md and its imports.
             2. Run `gh pr view ${{ github.event.pull_request.number }}` to understand the PR intent.
 
             ## Step 3: Review Process
@@ -513,7 +513,7 @@ jobs:
             ## What to Look For
             - **Bugs**: Logic errors, off-by-one, null/undefined access, race conditions, unhandled promise rejections
             - **Security**: Injection risks (command, SQL, XSS), secret exposure, unsafe permissions, missing input validation
-            - **Architecture**: Does the change follow patterns in CLAUDE.md (if it exists)? Are conventions consistent?
+            - **Architecture**: Does the change follow the project guidance read during setup? Are conventions consistent?
             - **Language-specific**: Type safety, idiomatic patterns, proper use of language features
             - **Resource leaks**: Unclosed connections, missing event listener cleanup, timer leaks
 
@@ -604,7 +604,7 @@ jobs:
             REPO: ${{ github.repository }}
 
             You are a helpful AI assistant for this project.
-            Read CLAUDE.md if it exists to understand the project architecture and conventions.
+            Read AGENTS.md if it exists to understand the project architecture and conventions; otherwise read CLAUDE.md and its imports.
 
             When responding:
             1. Always read the relevant source files to understand full context before answering.

.claude/skills/ship/SKILL.md

@@ -39,9 +39,11 @@ argument-hint: "[commit message or description of changes]"
 - 如果变更涉及某个 plan 的 `related_paths`，检查该 plan 的 `status` 和 `last_updated` 是否需要更新
 - 如果 plan 的功能已全部实现，提醒用户将 status 改为 `completed`
 
-#### 3c. CLAUDE.md 一致性
+#### 3c. AGENTS.md 一致性
 
-检查 `CLAUDE.md` 中引用的路径是否仍然有效，以及本次变更是否引入了 CLAUDE.md 应记录但未记录的内容（新目录、新工具、新工作流）。
+检查 `AGENTS.md` 中引用的路径是否仍然有效，以及本次变更是否引入了 AGENTS.md 应记录但未记录的内容（新目录、新工具、新工作流）。
+
+其他仓库若仍以 `CLAUDE.md` 为规范来源，检查其正文及导入内容。本仓库的 `CLAUDE.md` 仅为兼容导入，规范更新应写入 `AGENTS.md`。
 
 #### 3d. 用户指南检查
 

.github/workflows/claude-comment.yml

@@ -70,7 +70,7 @@ jobs:
             REPO: ${{ github.repository }}
 
             You are a helpful AI assistant for this TypeScript/Node.js project.
-            Read CLAUDE.md first to understand the project architecture and conventions.
+            Read AGENTS.md first to understand the project architecture and conventions.
 
             When responding:
             1. Always read the relevant source files to understand full context before answering.

.github/workflows/pr-review.yml

@@ -75,7 +75,7 @@ jobs:
 
             ## Step 2: Setup
 
-            1. Read CLAUDE.md to understand the project architecture and conventions.
+            1. Read AGENTS.md to understand the project architecture and conventions.
             2. Run `gh pr view ${{ github.event.pull_request.number }}` to understand the PR intent.
 
             ## Step 3: Review Process
@@ -88,7 +88,7 @@ jobs:
             ## What to Look For
             - **Bugs**: Logic errors, off-by-one, null/undefined access, race conditions, unhandled promise rejections
             - **Security**: Injection risks (command, SQL, XSS), secret exposure, unsafe permissions, missing input validation
-            - **Architecture**: Does the change follow patterns in CLAUDE.md? ESM imports with .js extensions? Proper singleton usage?
+            - **Architecture**: Does the change follow patterns in AGENTS.md? ESM imports with .js extensions? Proper singleton usage?
             - **TypeScript**: Unsafe `any` types, incorrect generics, missing error types, async/await pitfalls
             - **Resource leaks**: Unclosed connections, missing event listener cleanup, timer leaks