vba/AGENTS.md

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.

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