# AGENTS.md - VBA Coding Constraints

## Project Overview
- **Project Name**: Commuter Allowance Editor
- **App**: Excel 2021
- **Purpose**: Edit commuter certification by referencing master data

## VBA Coding Constraints
### Naming Conventions
- **Module**: `mod[Domain][Action]` (e.g., `modReportGenerator`, `modDataValidation`)
- **Class Module**: `cls[Noun]` (e.g., `clsInvoiceParser`, `clsDbConnection`)
- **Public Procedure**: PascalCase (e.g., `GenerateMonthlyReport`)
- **Private Procedure**: camelCase with prefix (e.g., `parseRawData`, `validateInput`)
- **Constant**: `UPPER_SNAKE_CASE` with scope prefix (e.g., `PUB_MAX_RETRY_COUNT`, `PRV_DEFAULT_PATH`)
- **Variable**: Hungarian or semantic naming, but **must be consistent across the project**

### Mandatory Rules
- ✅ Every module must start with `Option Explicit`
- ✅ All Public procedures must have a comment header (description, params, return value, author, date)
- ✅ `On Error Resume Next` is completely forbidden. Missing sheet/object should raise error directly via `Err.Raise ERR_SHEET_MISSING`. Do not suppress errors when checking if a sheet/worksheet/object exists.
- ✅ Object variables must be explicitly `Set obj = Nothing` in `Finally` block or at end of procedure
- ✅ Long operations must disable `ScreenUpdating`, `Calculation`, `EnableEvents` and restore on exit
- ✅ Comments must be in **English only**. No Chinese, Japanese, or Korean characters allowed in any code comments or inline documentation
- ❌ Forbidden: `Select` / `Selection` / `ActiveCell`. Always reference Range/Worksheet objects directly
- ❌ Forbidden: hardcoded file paths or connection strings. Use config sheet or constants module
- ❌ Forbidden: non-English comments (Chinese / Japanese / Korean)

### Code Review Checklist

**Before editing**
- Read the entire function from first line to last line (not just the lines you plan to change)
- Find all call sites that reference the function or data structure you are about to modify

**After editing**
- Read the entire function from first line to last line again
- Verify: are all variables declared, are scopes correct, is the logic complete
- Go through every call site one by one to confirm compatibility

**When the user asks "Are you sure?"**
- Actually re-read the relevant code instead of saying "looks fine"
- grep all references and verify them one by one

**Key principle**
- Never skip context — do not look at only the diff and call it done
- The compiler cannot catch logic errors or missing variable declarations — only human review can
- Read the whole function, read all call sites — no exceptions

## Design Document

**Primary reference**: `documents/Tukin_Design_Document.md`

Before editing any sheet class or cache logic, **read the design document first**. It contains:
- Sheet column layouts with HeaderRow/StartRow/StartCol/EndCol per `RefreshSheetDict`
- Cache key/value structures for every CACHE_* constant
- Data flow diagrams for C1 editing cascade and CSV import
- Column layout reference (C1 has 58 columns, C to BG)
- All known issues and their fix status

**Rule**: Do not guess sheet layout or cache structure. Look it up in the design document.

**When cache structure is modified**: Update the design document accordingly — including CACHE_* constant table, cache architecture section, and any affected data flow diagrams.

vba/
  AGENTS.md, README.md, .gitignore, LICENSE
  通勤手当テンプレート2026xxxx.xlsm  (latest date version)
  data/                     CSV master data (14 files)
  documents/                design docs
    Tukin_Design_Document.md  — master design doc: sheet layouts, cache architecture, column reference, data flow
    checklist-2026-05-27.md  — audit checklist (historical)
  sql/                      DB definitions (4 files)
  src/sh/
    juk/                    address module
      init_module/Import_modules.bas
      module/Common_Button.bas
    tuk/                    commuter module
      init_module/
        Import_modules.bas
        Test_Cache.bas
      module/
        Common_Button.bas (306 lines)
        Common_Constants.bas
        Common_File_Utils.bas (347 lines)
        Common_Functions.bas (486 lines)
        Common_Global_Cache.bas (586 lines)
        Common_Selector.bas (161 lines)
        Common_Shape.bas
      sheet/                 sheet classes (13 files)
        C1.cls (846 lines) - commuter allowance editor
        M1.cls (167 lines) - section master
        M2.cls (400 lines) - section detail master
        O1.cls (5 lines) - address master
        O2.cls (6 lines) - sender master (507)
        O3.cls (61 lines) - (220) notification reason
        T1.cls (54 lines) - commutation pass master
        T2.cls (114 lines) - ticket master
        T3.cls (74 lines) - master 246
        Z1.cls (64 lines) - transport master (222)
        Z2.cls (54 lines) - decision master (223)
        Z3.cls (57 lines) - monthly amount decision master (224)
        Z4.cls - (221) route station name

Sheet class prefixes: C=commuter editing, M=section master, O=other, T=commuter route, Z=master config