From ee1da2ffa692aaa8c12e7b6f3d0af5ebd8bd900f Mon Sep 17 00:00:00 2001
From: jackwener <jakevingoo@gmail.com>
Date: Thu, 16 Apr 2026 23:38:47 +0800
Subject: [PATCH] docs: add CLAUDE.md and AGENTS.md with cross-platform check
 rules

---
 AGENTS.md | 33 +++++++++++++++++++++++++++++++++
 CLAUDE.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 85 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..0452a75
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,33 @@
+# wx-cli Agent Rules
+
+## 每次改完代码后必须做的事
+
+1. **`cargo check`** — 改任何 `.rs` 文件后立刻运行，不通过不提交
+2. **改了跨平台代码时加运行跨平台 check：**
+   ```bash
+   cargo check --target x86_64-unknown-linux-gnu
+   cargo check --target x86_64-pc-windows-msvc
+   ```
+3. **改了 `Cargo.toml` 版本号时：** `cargo update --workspace`
+
+## 禁止行为
+
+- 不能在 `cargo check` 失败的情况下 commit
+- 不能只在 macOS 本地 check 就认为跨平台没问题
+- 不能改完 `Cargo.toml` 不更新 `Cargo.lock` 就打 tag
+
+## 常见陷阱
+
+| 陷阱 | 正确做法 |
+|------|----------|
+| `libc::__error()` 在 `#[cfg(unix)]` 里 | 用 `std::io::Error::last_os_error()` |
+| 把通用 dep 放到 `[target.cfg(windows).dependencies]` 后面 | TOML section 是贪婪的，通用 dep 必须在 target section 之前 |
+| 改版本号忘更新 Cargo.lock | `cargo update --workspace` |
+| Windows 代码用 trait method 忘 import trait | `use std::os::windows::process::CommandExt` 等 |
+| `#[cfg(windows)]` 里引用了未定义的函数 | 跨平台 check 会发现 |
+
+## Push 规则
+
+- remote 名称：`wx-cli`，使用 SSH
+- 每次 commit 后立刻 push
+- 打 tag 用 `git tag vX.Y.Z && git push wx-cli vX.Y.Z`
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..b4a81bf
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,52 @@
+# wx-cli Project Rules
+
+## After Every Code Change
+
+**Rust 代码改动后，必须立刻运行：**
+
+```bash
+cargo check
+```
+
+不允许在 `cargo check` 通过之前提交或推送。
+
+**改动涉及跨平台代码（`#[cfg(...)]` / `Cargo.toml` dependencies）时，额外运行：**
+
+```bash
+cargo check --target x86_64-unknown-linux-gnu
+cargo check --target x86_64-pc-windows-msvc
+```
+
+这两条命令在 macOS 上可以执行（只做类型检查，不需要链接器），用于提前暴露 Linux/Windows 特有的编译错误。
+
+## Cargo.toml 修改规则
+
+- 修改版本号后，必须运行 `cargo update --workspace` 更新 Cargo.lock
+- 添加/移动 `[target.'cfg(...)'.dependencies]` section 时，确认后续依赖没有被意外归入该 section（TOML section 持续到下一个 header）
+- 改完后运行 `cargo check` 验证
+
+## Git 规则
+
+- 每次 commit 后必须 push（`git push wx-cli main`）
+- 打 tag 前确认 `cargo check` 和 `cargo update --workspace` 都已完成
+- remote 使用 `wx-cli`（SSH），不用 `origin`
+
+## 平台兼容性检查清单
+
+改动以下内容时必须做跨平台 check：
+
+- [ ] `libc::` 调用 → 确认函数在 Linux 和 macOS 都存在（`__error` 是 macOS 专属，用 `std::io::Error::last_os_error()` 代替）
+- [ ] `#[cfg(unix)]` 块 → unix 包括 macOS 和 Linux，不能用 macOS 专属 API
+- [ ] `Cargo.toml` dependency section 顺序 → 检查是否有 dep 意外落入 target section
+- [ ] Windows named pipe 代码 → 确认函数都已定义，trait import 齐全
+
+## CI 结构
+
+```
+check job（ubuntu）
+  └── cargo check --target linux-x86, linux-arm64, windows-x86
+        ↓ 通过后
+build jobs（5平台并行）
+        ↓ 全部通过后
+publish-npm job
+```