From f68741f1905a9a59fcdaf5fd469c6fde7f603ae9 Mon Sep 17 00:00:00 2001
From: chuan <haeer98@outlook.com>
Date: Fri, 14 Aug 2026 21:18:14 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=BC=80=E5=8F=91?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md   |  5 +++++
 docs/dev.md | 17 +++++++++++++++++
 2 files changed, 22 insertions(+)
 create mode 100644 docs/dev.md

diff --git a/AGENTS.md b/AGENTS.md
index 1fa1fe7..6cb3d22 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,3 +11,8 @@
 - `CLIProxyAPI` 原始项目
 - `cpa-plugin-key-billing` CLIProxyAPI 下游 API Key 计费与订阅额度插件
 - `cpa-usage-keeper` 用量持久化与分析面板
+
+## DO
+
+- 阅读 `docs/dev.md` 了解开发前置知识
+- 阅读 `TODOS.md` 了解计划
diff --git a/docs/dev.md b/docs/dev.md
new file mode 100644
index 0000000..a7306bb
--- /dev/null
+++ b/docs/dev.md
@@ -0,0 +1,17 @@
+# 开发与测试
+
+开发按依赖从少到多推进：先确定数据和规则，再实现存储与服务，最后接入外部协议和界面。核心逻辑不依赖框架类型，协议转换集中在边界层。涉及持久化时，先定义迁移和历史数据语义
+
+开发的核心在于每一步的可预见性与可测试性
+
+开始前确认运行环境、配置加载方式和启动入口。开发与测试使用相同环境，不临时更换 Shell、依赖来源或配置路径。启动后先检查进程和健康状态，再验证功能
+
+测试分三层：
+
+- 单元测试验证规则和边界值
+- 存储测试验证持久化、迁移和并发
+- 集成测试验证完整调用链
+
+每项功能同时覆盖成功、失败、取消、重试和乱序
+
+集成测试应从公开入口产生数据，并使用日志、数据库或独立系统交叉核对，直接修改数据库只能用于迁移测试