From f499645cdc31232c9ba6e1575c35a42f278b8f06 Mon Sep 17 00:00:00 2001 From: ryan Date: Wed, 12 Aug 2026 12:02:14 +0800 Subject: [PATCH] chore: guideline --- AGENTS.md | 123 ++++++++++++++++++++++++++++-------------------------- CLAUDE.md | 1 + Claude.md | 1 - 3 files changed, 65 insertions(+), 60 deletions(-) create mode 100644 CLAUDE.md delete mode 120000 Claude.md diff --git a/AGENTS.md b/AGENTS.md index f254f304..29580fbb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,68 @@ -# AGENTS.md — Wavelet AI 助手工作操作手册 +# AGENTS.md -本文件面向 AI 开发助手，定义其职责与操作规范。 +Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed. + +**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. + +## 1. Think Before Coding + +**Don't assume. Don't hide confusion. Surface tradeoffs.** + +Before implementing: +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them - don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +## 2. Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +## 3. Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it - don't delete it. + +When your changes create orphans: +- Remove imports/variables/functions that YOUR changes made unused. +- Don't remove pre-existing dead code unless asked. + +The test: Every changed line should trace directly to the user's request. + +## 4. Goal-Driven Execution + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: +- "Add validation" → "Write tests for invalid inputs, then make them pass" +- "Fix the bug" → "Write a test that reproduces it, then make it pass" +- "Refactor X" → "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan: +``` +1. [Step] → verify: [check] +2. [Step] → verify: [check] +3. [Step] → verify: [check] +``` + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. + +--- + +**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes. ## Git 提交规范 @@ -39,63 +101,6 @@ - **后端**：Go 1.25+、Gin、GORM、PostgreSQL、ClickHouse、Redis、Asynq、Cobra、Viper、Swaggo、OpenTelemetry、Zap、AWS SDK v2。 - **前端**：Next.js (App Router)、TypeScript、Tailwind CSS、pnpm、shadcn/ui。 -### 顶层目录 -- `main.go`：程序入口，委派给 `internal/cmd`。 -- `config.example.yaml` / `config.yaml`：配置文件模板与本地配置。 -- `docker/`：容器化部署 Dockerfile。 -- `docs/`：自动生成的 Swagger 文档（请勿手动编辑）。 -- `frontend/`：Next.js 前端应用。 -- `internal/`：后端核心私有代码。 -- `pkg/`：公共通用 Go 工具库（不包含具体业务）。 -- `scripts/`：本地开发与 CI 脚本。 -- `support-files/`：部署与 SQL/环境辅助文件。 -- `bin/` / `data/` / `uploads/`：编译二进制产物、本地数据文件与上传存储目录。 - -### 后端目录 (`internal/`) -- `internal/cmd/`：Cobra CLI 命令入口（API/Worker/Scheduler）。 -- `internal/platform/`：进程与跨模块装配。 - - `bootstrap/`：应用装配根，集中注册 Task、推送订阅、域事件监听器及进程级初始化。 - - `lifecycle/`：进程 shutdown hook。 -- `internal/infra/`：接入外部世界与 Wavelet 运行时配置的实现（非业务用例）。 - - `config/`：Viper 启动配置加载与映射结构体。 - - `persistence/`：PostgreSQL/Redis/ClickHouse 连接池、goose 迁移（`migrator/goose/`）、batchwriter、idgen（Go 包名仍为 `db`）。 - - `objectstore/`：对象存储多后端适配（Local/S3/R2/OSS/WebDAV；原 `internal/storage`）。 - - `diskcache/`：读 system_config 的磁盘缓存包装（引擎在 `pkg/cache/disk`）。 - - `task/`：Asynq 运行时、worker/scheduler、任务元数据。 -- `internal/shared/`：跨层无 IO 约定（`response` envelope、通用错误文案等）。 -- `internal/router/`：全局唯一 HTTP 路由注册点。 -- `internal/apps/`：按功能（Feature-based）划分模块的 Handler 与业务逻辑（管理端位于 `admin/`）。 -- `internal/apps/upload/`：文件上传服务、访问控制与 WebP 压缩。 -- `internal/model/`：GORM 数据模型定义与模型层方法。 -- `internal/repository/`：数据访问（过渡期包级函数；后续接口化）。 -- `internal/util/`：纯底层无框架依赖工具函数。 -- `internal/listener/`：域事件分发层（解耦业务域与运维/推送模块；过渡）。 -- `internal/testhelper/`：后端测试共享 Helper。 -- `internal/buildinfo/`：编译与构建元数据。 - -新增技术能力默认放进 `infra/` 或 `platform/` 子树，禁止再在 `internal/` 顶层平铺杂散包。 - -### 公共底层包 (`pkg/`) -- `pkg/cache/disk/`：纯底层磁盘缓存引擎。 -- `pkg/cap/`：通用验证码库。 -- `pkg/httppool/`：带 OTel 链路追踪的共享 HTTP 客户端连接池。 -- `pkg/logger/`：Zap / OTel 结构化日志工具。 -- `pkg/push/`：推送渠道 SDK 集成（Lark / Telegram / Email）。 -- `pkg/mail/`：邮件发送客户端。 -- `pkg/trace/`：OpenTelemetry 链路配置。 -- `pkg/util/`：无副作用系统工具（Crypto / Password / UUID 等）。 - -### 前端目录 (`frontend/`) -- `frontend/app/`：Next.js App Router 路由与页面。 -- `frontend/components/ui/`：shadcn/ui 基础通用组件。 -- `frontend/components/common/`：跨页面的业务通用组件。 -- `frontend/components/layout/`：Header / Sidebar / Footer 页面框架组件。 -- `frontend/components//`：特定业务域的 UI 组件（如 `auth/`、`home/`）。 -- `frontend/lib/services/`：基于 `BaseService` 继承的类型化前端 API 服务。 -- `frontend/i18n/`：前端国际化配置（locale 解析、cookie、request config）。 -- `frontend/messages/`：i18n 文案目录（`zh-CN.json` / `en.json`）。 -- `frontend/contexts/` / `hooks/` / `lib/` / `types/` / `public/`：全局状态、Hook、客户端工具、TS 类型定义与静态资源。 - ## 后端开发规范 ### API 响应规范 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..eef4bd20 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md \ No newline at end of file diff --git a/Claude.md b/Claude.md deleted file mode 120000 index 96808718..00000000 --- a/Claude.md +++ /dev/null @@ -1 +0,0 @@ -Agents.md \ No newline at end of file