diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..fba602e
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,52 @@
+# TODO — Teknik Borçlar ve Ertelenen Kararlar
+
+Bu dosya, kasıtlı olarak ertelenen teknik kararları ve ileride ele alınması gereken
+tasarım noktalarını tutar. Her giriş hangi issue'ya bağlı olduğunu belirtir.
+
+---
+
+## #modül-scope — IRFunction.moduleId: Modül-düzeyi değişken izolasyonu
+
+**Etkilenen dosyalar:**
+- `src/ir/instruction.hpp` — `LOAD_GLOBAL` / `STORE_GLOBAL` yorumları
+- `src/ir/ir_program.hpp` — `globalCount`, `globalNames`
+- `src/vm/interpreter.hpp` — `globalSlots_`
+- `src/vm/interpreter.cpp` — `LOAD_GLOBAL` / `STORE_GLOBAL` case'leri
+
+**Mevcut durum (tek dosya):**
+`LOAD_GLOBAL dest, N` → `globalSlots_[N]` — düz vektör, tek modül varsayımı.
+Tek dosyada bu doğru çalışır; `globalSlots_[0]` her zaman bu dosyanın 0. modül-değişkenidir.
+
+**Çok modüllü derlemede yapılması gereken:**
+Her `IRFunction`'a `std::string moduleId` (veya `int moduleIndex`) alanı ekle.
+`Interpreter`'da `globalSlots_` yerine `std::unordered_map<std::string, std::vector<Value>> moduleSlots_` tut.
+`LOAD_GLOBAL` çalışırken `frame.function->moduleId` ile doğru modülün slot alanına bak.
+
+```
+// Hedef tasarım (modül sistemi gelince):
+case Opcode::LOAD_GLOBAL:
+    frame.slots[instr.dest] = moduleSlots_[frame.function->moduleId][instr.intValue];
+    break;
+```
+
+**Ne zaman:** Modül sistemi issue'ları (#3 import sözdizimi, #4 görünürlük, #5 çoklu dosya)
+ele alınırken bu değişikliği de kapsama al.
+
+---
+
+## #sembol-modül — Symbol.sourceModule: Sembol tablosunda açık modül kimliği
+
+**Etkilenen dosyalar:**
+- `src/symbol/symbol.hpp` — `Symbol` struct
+
+**Mevcut durum:**
+`Symbol.definitionLoc.filePath` dosya yolunu tutuyor — modül bilgisi dolaylı olarak var.
+Ama doğrudan `moduleId` / `moduleName` alanı yok; filtre/lookup için her seferinde
+`definitionLoc.filePath`'i ayrıştırmak gerekir.
+
+**Yapılması gereken:**
+`Symbol` struct'ına `std::string sourceModule` alanı ekle (modül adı veya dosya yolu).
+Özellikle cross-module sembol çözümleme, LSP "tanıma git" ve hata mesajlarında
+"hangi modülden geldi" bilgisi için kritik.
+
+**Ne zaman:** `#3` (import sözdizimi) veya `#4` (görünürlük) issue'larında.
diff --git a/src/ir/instruction.hpp b/src/ir/instruction.hpp
index 3d11db4..c59253a 100644
--- a/src/ir/instruction.hpp
+++ b/src/ir/instruction.hpp
@@ -82,9 +82,13 @@ enum class Opcode {
 
     RETURN,        // Bu frame'i kapat, slots[src]'yi caller'a ilet.
 
-    // --- Global değişken erişimi ---
-    LOAD_GLOBAL,   // slots[dest] = globalSlots[intValue]
-    STORE_GLOBAL,  // globalSlots[intValue] = slots[src]
+    // --- Modül-düzeyi değişken erişimi ---
+    // "Global" değil: her değişken kendi dosyasına (modülüne) aittir.
+    // Başka modüller bu alana doğrudan erişemez; yalnızca export/import ile ulaşabilir.
+    // TODO(#modül-scope): IRFunction.moduleId eklenerek çok-modüllü derlemede
+    //   her fonksiyonun kendi modülünün slot alanına bakması sağlanacak (bkz. TODO.md).
+    LOAD_GLOBAL,   // slots[dest] = moduleSlots[intValue]  (bu modülün modül-düzeyi değişkeni)
+    STORE_GLOBAL,  // moduleSlots[intValue] = slots[src]
 
     // --- Dış dünya (FFI — Foreign Function Interface) ---
     CALLHOST,      // Host (C++) fonksiyonunu çağır. Şu an sadece "print" destekli.
diff --git a/src/ir/ir_generator.cpp b/src/ir/ir_generator.cpp
index b67d3d2..b98593d 100644
--- a/src/ir/ir_generator.cpp
+++ b/src/ir/ir_generator.cpp
@@ -17,7 +17,8 @@
 IRProgram IRGenerator::generate(ASTNode* programNode, SymbolTable& /*symbolTable*/) {
     IRProgram program;
 
-    // 1. Geçiş: global VariableDecl'leri topla ve kayıt et
+    // 1. Geçiş: modül-düzeyi VariableDecl'leri topla ve kayıt et
+    // "Global" değil — bu dosyanın (modülün) kendi değişkenleri.
     std::vector<VariableDeclNode*> globalVars;
     for (ASTNode* child : programNode->getChildren()) {
         if (child->kind == ASTKind::VariableDecl) {
diff --git a/src/ir/ir_program.hpp b/src/ir/ir_program.hpp
index 59caf89..7fcb838 100644
--- a/src/ir/ir_program.hpp
+++ b/src/ir/ir_program.hpp
@@ -29,7 +29,11 @@ struct IRProgram {
     // Ekleme sırası (dump'ta orijinal sırayla göstermek için)
     std::vector<std::string> functionOrder;
 
-    // Global değişkenler (LOAD_GLOBAL / STORE_GLOBAL için)
+    // Modül-düzeyi değişkenler (LOAD_GLOBAL / STORE_GLOBAL için)
+    // Bunlar "global" değil — bu IRProgram'ın temsil ettiği tek modüle aittir.
+    // Çok-modüllü derlemede her modülün kendi IRProgram'ı (veya ayrı slot alanı) olur.
+    // TODO(#modül-scope): moduleId alanı eklenince Interpreter bu alana
+    //   frame.function->moduleId üzerinden erişecek (bkz. TODO.md).
     int                      globalCount = 0;
     std::vector<std::string> globalNames; // index → isim (dump için)