@ -2,133 +2,322 @@
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
## 语言规范
SysY 编译器课程实验 — a progressive compiler (Lab1–
主要使用中文交流、写注释、写文档和 commit message。代码标识符（ ）
## Build Commands
## 项目概述
SysY → ARM64/AArch64 编译器， （ ）
## 构建
### Prerequisites
```bash
# Install dependencies (Ubuntu 22.04 / WSL)
sudo apt install -y build-essential cmake git openjdk-11-jre llvm clang gcc-aarch64-linux-gnu qemu-user
# 首次：生成 ANTLR Lexer/Parser
mkdir -p build/generated/antlr4
java -jar third_party/antlr-4.13.2-complete.jar -Dlanguage=Cpp -visitor -no-listener \
-Xexact-output-dir -o build/generated/antlr4 src/antlr4/SysY.g4
# 全量构建
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCOMPILER_PARSE_ONLY=OFF
cmake --build build -j "$(nproc)"
```
### Generate ANTLR Lexer/Parser (required before first build)
可执行文件：`./build/bin/compiler`
## 编译器 CLI（ ）
```bash
mkdir -p build/generated/antlr4
java -jar third_party/antlr-4.13.2-complete.jar \
-Dlanguage=Cpp -visitor -no-listener -Xexact-output-dir \
-o build/generated/antlr4 src/antlr4/SysY.g4
compiler -S -o output.s input.sy # 汇编输出（比赛标准）
compiler -S -o output.s input.sy -O # 带优化
compiler --emit-ir input.sy # 打印 IR
compiler --emit-parse-tree input.sy # 打印语法树
```
## 架构
编译管线：`SysY → [frontend] ANTLR 语法树 → [sem] 语义分析 → [irgen] IR 生成 → [ir/passes] IR 优化 → [mir/Lowering] MIR 降级 → [mir/RegAlloc] 寄存器分配 → [mir/FrameLowering] 栈帧 → [mir/peephole] 窥孔 → [mir/AsmPrinter] AArch64 汇编`
源码目录：
- `src/frontend/` — ANTLR 驱动、语法树打印
- `src/sem/` — Sema、SymbolTable、ConstEval
- `src/irgen/` — 语法树 → LLVM IR 翻译
- `src/ir/` — IR 数据结构（ ） ，
- `src/mir/` — 机器 IR（ ） ，
- `src/include/` — 各模块头文件
关键设计： ； ； ； ； ，
---
# 一、安全第一：编译器优化的生存法则
## 竞赛红线（零容忍，违反即取消成绩）
1. ** 禁止投机优化**：不得识别特定函数名、字符串、输入特征来激活优化
2. ** 禁止硬编码结果**：不得对计算结果预设答案
3. ** 禁止依赖 UB**：不得假设数组不越界、除法不溢出等
4. ** 优化必须通用**：对所有合法 SysY2026 程序语义保持
## 段错误预防（从历史故障中提炼的高危区）
| 区域 | 常见根因 | 预防规则 |
|------|----------|----------|
| 寄存器分配 | 合并后颜色/degree 不一致 | 合并后总是重算 degree；
| 栈帧 | 大偏移量（>12KB）
| spill | 无限 spill 循环 | 大函数（>120 vregs）
| 活跃合并 | 干涉图边不完整 | Briggs 保守测试：邻居 degree≥K 计数 < K |
| 迭代器 | move_adj 自环导致失效 | 合并前检查 u != v，
## 优化安全性自检清单
实现任何优化变换时必须确认：
- [ ] 对所有合法 SysY2026 程序，语义是否保持？
- [ ] 副作用顺序是否保持？ （
- [ ] 浮点语义是否保持？（不能随意重关联）
- [ ] 是否有针对特定测试用例的投机判断？（有则违规）
## 修改范围限制
- 一次只改一个 pass 或一个模块
- 寄存器分配和 IR 优化不能混在一次改动中
- 改 MIR 层前先确认 IR 层正确性基线
---
# 二、性能北极星：指令数驱动的开发循环
## 核心循环（不可跳步）
```
假设 → 测量基线 → 实现 → 正确性验证 → 性能测量 → 决策
↑ |
└──────────── 回退或调整 ←─────────────────────────────┘
```
| 步骤 | 命令/动作 |
|------|-----------|
| 假设 | 写一句话：「改 X，
| 基线 | `./count_asm.sh` |
| 实现 | 写代码 |
| 正确性 | `./2026test.sh -c functional -x && ./2026test.sh -c h_functional -x` |
| 性能 | `./count_asm.sh` |
| 决策 | 对比基线，判断合并/调整/回退 |
## 指令数作为核心指标
指令数（`wc -l` 汇编）无测量噪声、可复现。目标硬件 Cortex-A53 为顺序核，指令数与运行时间相关性较高。指令数减少是积极信号但非绝对保证。
## 性能退化门禁
| 规模 | 动作 |
|------|------|
| 大面积退化（>5 用例） | ** 阻止合并**，分析根因 |
| 少量退化（ < 5 % ） | 标 记 关 注 ， 分 析 根 因 ， 记 录 到 commit |
| 零散退化（ < 2 % ） | 可 容 忍 ， 注 明 到 commit |
| 零退化 + 改善 | ** 理想**，更新基线，合并 |
## 基线管理
`指令数基线.md` 记录历史最低值，`count_asm.sh` 自动维护——新值更低时才更新。性能改善 commit 须附带基线更新。
---
# 三、AI 协作协议
## 任务规模 → 流程映射
| 规模 | 特征 | 流程 |
|------|------|------|
| 轻量 | 单文件、阈值调整、明显 bug（ < 30 分 钟 ） | 直 接 改 → 快 门 禁 → commit |
| 中量 | 跨文件、新 pass、算法改动（
| 重量 | 寄存器分配重构、IR 框架（多日） | office-hours → GSD 全流程 → 全门禁 → extract-learnings |
## 提示词模式
- ** 先说为什么再说做什么**：告诉 AI 目标（「减少 spill 代码量」）而非操作（「修改 spillCost 函数」）
- ** 先计划后代码**：要求 AI 先提变更计划，审查通过后再写代码。即使是「简单」改动
- ** 显式约束前置**：一次性给出所有约束（红线、修改范围、语义安全要求）
- ** 小 diff（
## AI 不能做的事
- ** 不能自行验证自己生成的代码**——必须通过编译器运行和测试脚本等外部工具验证
- ** 不能决定核心算法设计**——可以建议和实现，最终设计由人审查
- ** 不能跳过门禁**——任何改动都必须过测试
- **AI 生成的测试不能作为唯一的正确性验证** ——需要独立的外部 oracle（
## DeepSeek 特化策略
- ** 开启 thinking mode**：复杂推理任务使用 `reasoning_effort: max`
- ** 利用上下文缓存**：同一文件反复读取几乎免费，大胆多次参考已有代码
- ** 分割大 prompt**：
- **C++ 代码 double-check** ：
## MCP 使用铁律
| 场景 | 工具 | 不要 |
|------|------|------|
| 查找符号 | `codegraph_search` | 不要 grep |
| 调用关系 | `codegraph_callers/callees` | 不要手动 Read 追踪 |
| 改动影响 | `codegraph_impact` | 不要猜测 |
| 代码区探索 | `codegraph_explore` （一次） | 不要逐个 codegraph_node |
| 字面量搜索 | `grep` | 不要用 codegraph 搜 |
| PR 管理 | `gh create_pr/create_review` | 不要手动 |
---
# 四、三层门禁
## 数据集优先级
- ** 一级**： ， ）
- ** 二级**：
## 快门禁（每次 commit 前，~2 分钟）
### Lab1 (frontend only — parse tree printing)
```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCOMPILER_PARSE_ONLY=ON
cmake --build build -j "$(nproc)"
./build/bin/compiler --emit-parse-tree test/test_case/functional/simple_add.sy
./2026test.sh -c functional -x & & ./2026test.sh -c h_functional -x
```
### Full build (all labs, including IR gen, optimization, and codegen)
通过标准：
## 中门禁（每次 merge 前，~10 分钟）
```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCOMPILER_PARSE_ONLY=OFF
cmake --build build -j "$(nproc)"
./2026test.sh -c functional -x
./2026test.sh -c h_functional -x
./2026test.sh -c performance -x
./count_asm.sh
```
## Compiler Usage
通过标准：
## 全门禁（关键节点，~30 分钟）
```bash
# Competition format: compile to assembly
./build/bin/compiler -S -o output.s input.sy
./2026test.sh # 全量
# 历史数据集回归
for f in test_merged/**/*.sy; do
./scripts/verify_asm.sh "$f" --run -O || echo "FAIL: $f"
done
```
触发条件：
## 门禁纪律
- 绝不跳过门禁——改动能通过门禁才是真的「完成」
- 功能测试失败时绝不进入性能测量——先修正确性
- 门禁失败后修复再跑——不允许「先合并后修复」
---
# 五、代码与 Git 规范
# With optimization
./build/bin/compiler -S -o output.s input.sy -O1
## 命名
# Emit IR
./build/bin/compiler --emit-ir input.sy
- 变量：`snake_case`；函数/类：`PascalCase`；成员变量：`snake_case_`
- 标识符和文件名用英文
# Single test: compile, link, run with QEMU, and compare output
./scripts/verify_asm.sh test/test_case/functional/simple_add.sy --run
## 中文规范
# Same for IR path (uses llc + clang to compile/run)
./scripts/verify_ir.sh test/test_case/functional/simple_add.sy --run
注释、commit message、文档、错误信息用中文。IR/MIR 调试打印用英文。
```cpp
// 使用 Briggs 保守测试而非 George，
if (HasMovePair(u)) ReactivatePairs(u);
```
### CLI Options
| Flag | Effect |
|------|--------|
| `-S` | Emit assembly (default when no mode specified) |
| `-o <file>` | Output file path |
| `-O` , `-O1` , `-O2` , `-O3` | Optimization level |
| `--emit-parse-tree` | Print ANTLR parse tree |
| `--emit-ir` | Print LLVM-style IR |
| `--emit-asm` | Print AArch64 assembly |
| `-h` , `--help` | Show help |
## Git
## Testing
格式：`< type > (< scope > ): < 中文简述>`。一 commit 一逻辑变更。不提交编译或测试失败的代码。功能分支开发，
### Main test harness
```bash
# Run all 2026test functional tests with optimization
./2026test.sh
---
# 六、自进化机制
## 触发条件
# Functional tests only, max 10 cases, stop on first failure
./2026test.sh -c functional -n 10 -x
1. ** 故障驱动**：段错误、性能退化、测试失败 → 诊断根因 → 可预防则更新本规范
2. ** 成功固化**：新优化方法被验证有效 → 记录模式
3. ** 定期审查**：每两周 review 本规范，删除过时规则，强化有效规则
# Without optimization
./2026test.sh -O0
## 操作流程
```
故障发生 → 根因分析（中文 ≤100 字）
→ 可预防？
├─ 是 → 更新 CLAUDE.md 或 memory
└─ 否 → 只记录
```
### Legacy test scripts
```bash
./test1.sh # Lab1: syntax tree
./test2.sh # Lab2: IR generation
./test3.sh # Lab3: assembly generation
./test4.sh # Lab4: scalar optimization
./test5.sh # Lab5: register allocation
```
## Architecture
### Compiler Pipeline
```
SysY source (.sy) → ANTLR Lexer/Parser → AST (ANTLR parse tree)
→ Sema (name resolution, type checking) → IR (LLVM-style, load/store form)
→ IR Passes (Mem2Reg → LICM → ConstFold/Prop/DCE/CFG/CSE) → MIR (machine IR, AArch64)
→ RegAlloc → FrameLowering → Peephole → AArch64 Assembly output
```
### Source Layout
| Directory | Purpose |
|-----------|---------|
| `src/antlr4/SysY.g4` | ANTLR grammar for SysY language |
| `src/frontend/` | ANTLR driver + syntax tree printer (Lab1) |
| `src/sem/` | Semantic analysis: name binding, scope, type checking (Lab2 prep) |
| `src/irgen/` | IR generation via ANTLR visitor: Decl, Exp, Stmt, Func (Lab2) |
| `src/ir/` | LLVM-style IR: Value/User/Use hierarchy, Module/Function/BasicBlock, IRBuilder (Lab2) |
| `src/ir/passes/` | Scalar optimizations (Lab4): Mem2Reg, ConstFold, ConstProp, DCE, CFGSimplify, CSE, LICM |
| `src/ir/analysis/` | DominatorTree, LoopInfo |
| `src/mir/` | Machine IR + AArch64 backend (Lab3, Lab5): Lowering (IR→MIR), RegAlloc, FrameLowering, AsmPrinter |
| `src/mir/passes/` | MIR peephole pass |
| `src/utils/` | CLI argument parsing, logging |
| `src/include/` | **Build-time headers.** At build time CMake adds `src/include` as include path. |
| `include/` | **Platform-provided headers.** Gitignored — supplied externally by grading platform. Mirrors `src/include/` . |
| `sylib/` | SysY runtime library (sylib.c), linked into final executables |
| `scripts/` | verify_asm.sh, verify_ir.sh — single-case test helpers |
| `third_party/` | ANTLR jar + antlr4-runtime sources |
| `test/test_case/` | Reference test cases with expected outputs |
### Key Design Patterns
- **IR IR** : Lightweight LLVM-style IR with `Value → User → Instruction` class hierarchy and def-use chains via `Use` objects. `IRBuilder` appends instructions to a `BasicBlock` . The IR starts in load/store (alloca-based) form; `Mem2Reg` promotes allocas to SSA phi nodes.
- **MIR IR** : Lower-level, three-address machine IR using AArch64 opcodes and a union-like `Operand` (reg, vreg, imm, frame index, label, symbol). Purely a data container — no SSA, no def-use analysis.
- **ANTLR Visitor** : `IRGenImpl` extends the ANTLR-generated `SysYBaseVisitor` to walk the parse tree and emit IR. Each `visit*` method returns `std::any` (typically `ir::Value*` ).
- **Pass infrastructure** : Each IR pass is a standalone function (`RunMem2Reg`, `RunDCE` , etc.) taking a `Module&` . `PassManager` and `PassManagerModule` orchestrate them with fixed-point iteration (serialize, compare, re-run until convergence).
### Important Notes
- The `#if COMPILER_PARSE_ONLY` macro in `main.cpp` guards all code beyond Lab1. The CMake option `COMPILER_PARSE_ONLY` controls whether `sem` , `irgen` , and `mir` subdirectories are built.
- `include/` is in `.gitignore` and absent from the build include path. It is provided externally by the grading platform. When editing headers, work in `src/include/` .
- The grammar `SysY.g4` defines the SysY language subset: `int` /`float`/`void` types, arrays, `const` , `if` /`else`/`while`/`break`/`continue`/`return`, and C-like expressions including logical short-circuit `&&` /`||`.
- Commit message convention: `<type>(<scope>): <subject>` where type ∈ {feat, fix, refactor, docs, test, chore} and scope ∈ {frontend, irgen, backend, test, doc}.
## 有效性度量
- 同类 bug 是否再次出现
- 门禁是否在 commit 前拦截了问题
- 指令数趋势是否持续改善
---
# 七、Skill & MCP 最优编排
## 仅保留有用的工具
本项目是 C++ 编译器，以下可用工具**有价值**：
- **MCP** ： （ ） （ ）
- ** 流程 skill**：
- ** 门禁 skill**：
- ** 战略 skill**（ ） ：
以下**忽略**： （ ） （ ） （
## 三种模式
### 快刀（< 30 分 钟 ）
```
codegraph_context → 直接改 → 快门禁 → commit
```
只用 Superpowers 战术层。示例：调阈值、修明显 bug。
### 标准优化（
```
brainstorming → writing-plans → TDD → 快门禁 → gsd-code-review → 中门禁 → commit
```
**brainstorming 是强制的**——「太简单不需要设计」是反模式。
### 重器（多日）
```
office-hours → gsd-discuss → gsd-plan → gsd-execute（
→ 全门禁 → gsd-code-review → gsd-extract-learnings → ship
```
只在 3-4 个关键架构点使用。编译器反馈循环很快，偏向执行而非过度计划。
## 最高 ROI 组合
```
bug 发现 → codegraph_impact（ ）
→ gh create_issue（ ）
→ brainstorming（ ）
→ TDD（ ）
→ 实现 → verification（ ）
→ gh create_pr
```
每一步都有外部信号验证，避免 AI 自说自话。
## 自进化闭环
```
gsd-extract-learnings → 更新 CLAUDE.md/memory
↑ ↓
全门禁验证 下次任务自动加载
↑ ↓
实现优化 AI 知道上次的教训
```
