# AGENT_RULES.local

目的：记录 tsl-devkit 项目私有规则，优先级高于 `AGENT_RULES.md`。

## 架构参考

理解项目结构前，必须阅读 `memory-bank/architecture.md`，重点关注：

- Core / Manager / Provider / Language / Bridge 分层边界
- LSP 请求从 `Dispatcher` 到 Provider 的调用链
- Tree-sitter + AST + Semantic 的分析链路
- C++23 Modules 与构建约束

涉及协议与能力面时，还需同步阅读：

- `memory-bank/project-brief.md`
- `memory-bank/tech-stack.md`

## 代码/架构约束

- 禁止无需求变更 LSP 协议对外行为：`method` 字符串、协议字段命名、响应结构保持兼容
- 禁止破坏现有分层：Provider 不直接承载 Manager/Language 的底层实现细节
- 换行符必须遵循 `.gitattributes` 规则，以该文件中的配置为准
- 禁止提交构建产物和临时文件：`lsp-server/build/**`、运行日志、临时脚本输出
- `docs/standards/playbook/` 为 vendored 快照；更新优先使用 subtree + 同步脚本，不做无依据手改

## Tree-sitter / AST 变更规则

新增或修改语法/解析链路时：

1. 优先修改语法源和解析逻辑（如 `grammar.js`、AST 反序列化逻辑）
2. `lsp-server/src/tree-sitter/` 与 `lsp-server/test/test_tree_sitter/src/` 下同名 parser/scanner 文件必须保持一致
3. 修改 AST 节点结构时，同步更新 `types/deserializer/debug_printer/test` 路径
4. 对行为变更补最小复现测试（优先 `test_ast --self-test` 或对应目录单测）
5. 汇报中必须写清“语法层问题 / AST 层问题 / 语义层问题”归因

## 项目特有提示词

执行以下任务时必须先读取对应提示词：

| 任务类型 | 提示词路径 |
| --- | --- |
| 需求澄清 | `docs/prompts/coding/clarify.md` |
| 代码复盘/评审总结 | `docs/prompts/coding/review.md` |
| 代理行为/工作模式 | `docs/prompts/system/agent-behavior.md` |
| 生成新提示词 | `docs/prompts/meta/prompt-generator.md` |

## 测试与验证规则

- 执行测试前，若构建目录不可用，先按“标准构建命令”完成依赖安装与编译
- AST/解析改动至少执行：
  - `ctest --test-dir lsp-server/build/clang-linux/Release -R test_ast_unit --output-on-failure`
  - `ctest --test-dir lsp-server/build/clang-linux/Release -R test_ast_script --output-on-failure`
- Provider/协议改动至少执行：
  - `ctest --test-dir lsp-server/build/clang-linux/Release -R test_provider --output-on-failure`
  - `ctest --test-dir lsp-server/build/clang-linux/Release -R test_lsp_json --output-on-failure`
- 语义/符号改动至少执行：
  - `ctest --test-dir lsp-server/build/clang-linux/Release -R test_semantic --output-on-failure`
  - `ctest --test-dir lsp-server/build/clang-linux/Release -R test_symbol --output-on-failure`
- 若存在已知失败项，必须在汇报中标注失败文件、最小复现结果、是否与本次改动相关

## 标准构建命令（Linux / Clang）

默认构建目录：`lsp-server/build/clang-linux/Release`

```bash
# 1) 安装依赖（Conan）
CONAN_HOME=/tmp/conan-home conan install lsp-server \
  -pr:h=lsp-server/conan/profiles/linux-x86_64-clang \
  -pr:b=lsp-server/conan/profiles/linux-x86_64-clang \
  -of lsp-server/build/clang-linux/Release \
  --build=missing

# 2) 配置（CMake + Ninja）
cmake -S lsp-server -B lsp-server/build/clang-linux/Release -G Ninja \
  -DCMAKE_TOOLCHAIN_FILE=$PWD/lsp-server/build/clang-linux/Release/generators/conan_toolchain.cmake \
  -DBUILD_TESTS=ON

# 3) 编译
cmake --build lsp-server/build/clang-linux/Release
```

常用目标编译：

```bash
cmake --build lsp-server/build/clang-linux/Release --target tsl-server
cmake --build lsp-server/build/clang-linux/Release --target test_ast
```

## Git 提交规则

- 提交首行必须使用 `:emoji: type(scope): subject` 格式
- `emoji` 与 `type` 映射以 `docs/standards/playbook/docs/common/commit_message.md` 为准
- `subject` 使用英文（建议现在时/祈使句，不加句号）
- 不允许中文提交标题；中文说明放在 commit body

## 紧急处理

- 构建/测试环境异常（例如 Conan 缓存、CMake 缓存、路径映射问题）优先记录可复现命令与原始报错
- 若遇到跨环境阻塞，按 `AGENT_RULES.md` 的 `blocked: env:<环境>:<Task列表>` 规范记录并继续主循环

---

**最后更新**：2026-03-05