From 917f42d7aba22f77babb288b50e8f81a8504681d Mon Sep 17 00:00:00 2001
From: Bairan Zhang <zhangbairan@talkingq.com>
Date: Fri, 30 Jan 2026 15:43:38 +0800
Subject: [PATCH] Update repo guidelines and VS Code config

---
 .vscode/c_cpp_properties.json | 23 -----------------------
 .vscode/extensions.json       |  6 ++++++
 .vscode/launch.json           | 15 ---------------
 .vscode/settings.json         | 11 -----------
 AGENTS.md                     | 34 ++++++++++++++++++++++++++++++++++
 5 files changed, 40 insertions(+), 49 deletions(-)
 delete mode 100644 .vscode/c_cpp_properties.json
 create mode 100644 .vscode/extensions.json
 delete mode 100644 .vscode/launch.json
 create mode 100644 AGENTS.md

diff --git a/.vscode/c_cpp_properties.json b/.vscode/c_cpp_properties.json
deleted file mode 100644
index 48fa5bb..0000000
--- a/.vscode/c_cpp_properties.json
+++ /dev/null
@@ -1,23 +0,0 @@
-{
-  "configurations": [
-    {
-      "name": "ESP-IDF",
-      "compilerPath": "${config:idf.toolsPathWin}\\tools\\xtensa-esp-elf\\esp-14.2.0_20251107\\xtensa-esp-elf\\bin\\xtensa-esp32-elf-gcc.exe",
-      "compileCommands": "${config:idf.buildPath}/compile_commands.json",
-      "includePath": [
-        "${config:idf.espIdfPath}/components/**",
-        "${config:idf.espIdfPathWin}/components/**",
-        "${workspaceFolder}/**"
-      ],
-      "browse": {
-        "path": [
-          "${config:idf.espIdfPath}/components",
-          "${config:idf.espIdfPathWin}/components",
-          "${workspaceFolder}"
-        ],
-        "limitSymbolsToIncludedHeaders": true
-      }
-    }
-  ],
-  "version": 4
-}
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 0000000..22b26fe
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "espressif.esp-idf-extension",
+    "llvm-vs-code-extensions.vscode-clangd"
+  ]
+}
diff --git a/.vscode/launch.json b/.vscode/launch.json
deleted file mode 100644
index 2511a38..0000000
--- a/.vscode/launch.json
+++ /dev/null
@@ -1,15 +0,0 @@
-{
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "type": "gdbtarget",
-      "request": "attach",
-      "name": "Eclipse CDT GDB Adapter"
-    },
-    {
-      "type": "espidf",
-      "name": "Launch",
-      "request": "launch"
-    }
-  ]
-}
\ No newline at end of file
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 0f56e22..a6c369d 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -1,20 +1,9 @@
 {
-  "C_Cpp.intelliSenseEngine": "default",
-  "idf.espIdfPathWin": "C:\\Users\\Admin\\esp\\v5.5.2\\esp-idf",
-  "idf.pythonInstallPath": "C:\\Users\\Admin\\.espressif\\tools\\idf-python\\3.11.2\\python.exe",
   "idf.openOcdConfigs": [
     "board/esp32s3-builtin.cfg"
   ],
-  "idf.portWin": "COM3",
-  "idf.toolsPathWin": "C:\\Users\\Admin\\.espressif",
   "idf.customExtraVars": {
     "IDF_TARGET": "esp32s3"
   },
-  "clangd.path": "C:\\Users\\Admin\\.espressif\\tools\\esp-clang\\esp-19.1.2_20250312\\esp-clang\\bin\\clangd.exe",
-  "clangd.arguments": [
-    "--background-index",
-    "--query-driver=**",
-    "--compile-commands-dir=c:\\Users\\Admin\\OneDrive\\Project\\招财猫\\Stepper base\\build"
-  ],
   "idf.flashType": "UART"
 }
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..cc3deb9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,34 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `main/` holds the application entry point (`main.c`) and its build file (`main/CMakeLists.txt`).
+- `components/stepper_motor/` contains the reusable stepper motor component. Public headers live in `components/stepper_motor/include/` and source in `components/stepper_motor/stepper_motor.c`.
+- `build/` is generated by ESP-IDF/CMake; do not edit or commit build artifacts.
+- `sdkconfig` is the project configuration used by ESP-IDF; `sdkconfig.old` is a backup after config changes.
+
+## Build, Test, and Development Commands
+Run these from an ESP-IDF environment with `IDF_PATH` set:
+- `idf.py build` — configure and compile the firmware into `build/`.
+- `idf.py flash -p <PORT>` — flash to the connected device.
+- `idf.py monitor` — open the serial monitor.
+- `idf.py flash monitor -p <PORT>` — common flash + monitor workflow.
+- `idf.py menuconfig` — edit `sdkconfig` interactively.
+- `idf.py fullclean` — remove build output and cached configuration.
+
+## Coding Style & Naming Conventions
+- C code uses 4-space indentation with braces on the same line.
+- Use `lower_snake_case` for functions/variables, `UPPER_SNAKE_CASE` for macros, and `*_t` suffixes for typedefs.
+- Prefer `static` for file-local helpers and use `ESP_LOGx` for logging.
+- Keep component APIs in `components/<name>/include/` and include with quotes (e.g., `"stepper_motor.h"`).
+
+## Testing Guidelines
+- No automated test framework is configured in this repo.
+- Validate behavior on hardware after changes; include manual test steps and results in PR descriptions.
+
+## Commit & Pull Request Guidelines
+- Git history shows short, imperative summaries without scopes (e.g., "Initial commit").
+- PRs should include: a short description, hardware/board tested, and any notable serial output or behavior changes. Attach photos/videos when motion behavior changes.
+
+## Configuration & Hardware Notes
+- GPIO assignments and motion parameters are defined in `components/stepper_motor/include/stepper_motor.h`.
+- Update pin mappings and timing constants there if wiring or motor characteristics change.