From c0375af3e38f28d46985520efe7795d9b8245bd0 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Sun, 9 Aug 2026 16:28:35 +0800
Subject: [PATCH] docs: add native architecture guidance

---
 AGENTS.md              | 17 +++++++++++++----
 crates/AGENTS.md       | 18 ++++++++++++++++++
 scripts/dictionary.txt |  1 +
 3 files changed, 32 insertions(+), 4 deletions(-)
 create mode 100644 crates/AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
index 8a2d17ec..27ee7f4e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,6 +5,7 @@
 - Use repo Node.js/pnpm versions (`package.json`)
 - `pnpm` workspace; shared deps in `pnpm-workspace.yaml` catalogs
 - TypeScript, Rsbuild/Rslib/Rstest/Rslint, Prettier
+- Rust/Cargo workspace with a NAPI-RS binding under `crates/`
 
 ## Commands
 
@@ -24,12 +25,19 @@ pnpm check:spell
 
 # focused work
 pnpm --filter rstack build
+pnpm --filter rstack build:native
 pnpm --filter rstack test
 ```
 
 ## Testing
 
-- Run `pnpm build` once before `pnpm test` command
+- Run `pnpm build` and `pnpm --filter rstack build:native` before `pnpm test`
+
+## Native
+
+- Follow `crates/AGENTS.md` for Rust changes
+- Keep the JS bridge lazy; use the generated loader directly
+- Regenerate binding files with `build:native`
 
 ## Documentation
 
@@ -39,7 +47,8 @@ pnpm --filter rstack test
 ## Project structure
 
 ```text
-packages/rstack/       # CLI package
-examples/*             # example projects
-scripts/               # repo tooling
+crates/                 # Rust crates
+packages/rstack/        # CLI package and private native bridge
+examples/*              # example projects
+scripts/                # repo tooling
 ```
diff --git a/crates/AGENTS.md b/crates/AGENTS.md
new file mode 100644
index 00000000..b7178eac
--- /dev/null
+++ b/crates/AGENTS.md
@@ -0,0 +1,18 @@
+# AGENTS.md
+
+## Architecture
+
+- Keep `rstack-binding` a thin Node/NAPI adapter
+- Put reusable or domain logic in separate crates
+- Coordinate binding changes with the private JS loader and its Rstest coverage
+
+## Checks
+
+Run from the repository root:
+
+```bash
+cargo fmt --all -- --check
+cargo clippy --workspace --all-targets --locked -- -D warnings
+cargo test --workspace --locked
+pnpm --filter rstack build:native
+```
diff --git a/scripts/dictionary.txt b/scripts/dictionary.txt
index b582a20c..74ed3eac 100644
--- a/scripts/dictionary.txt
+++ b/scripts/dictionary.txt
@@ -1,5 +1,6 @@
 # Custom Dictionary Words
 applypatch
+clippy
 dirents
 errexit
 extglob