# CLAUDE.md ## Purpose This file defines how Claude and Claude-compatible coding agents should operate in this repository. Read `AGENTS.md` first. `AGENTS.md` is the primary development policy. This file defines agent workflow, reasoning discipline, project learning, and self-improvement behavior. --- # 1. Startup Procedure At the beginning of a development task: 1. Read `AGENTS.md`. 2. Read this `CLAUDE.md`. 3. Inspect relevant files before editing. 4. Search the repository for similar implementations. 5. Identify existing helpers and abstractions. 6. Determine the affected architectural layers. 7. Identify security-sensitive boundaries. 8. Identify tests relevant to the change. Do not immediately generate a new abstraction before understanding the existing project. --- # 2. Treat VBScript as a Language Requiring Agent-Level Static Analysis VBScript lacks many safeguards found in modern compiled languages. Therefore, while working, actively inspect for: ```text undeclared variables misspelled identifiers missing Set wrong argument counts implicit Variant conversions Null propagation Empty values Nothing references unexpected ByRef mutation invalid function return paths unsafe SQL unsafe HTML output broad error suppression resource leaks global-state coupling ``` Act as a compiler substitute. --- # 3. Think in Boundaries Before changing code, determine which layer owns the behavior. Preferred direction: ```text Request ↓ Controller ↓ Service ↓ Repository ↓ Database ``` Views should receive prepared data. Do not bypass layers for convenience. --- # 4. Avoid Architectural Drift When adding functionality, prefer the project's existing good pattern. Do not create: ```text CustomerManager CustomerHandler CustomerEngine CustomerProcessor CustomerHelper ``` if `CustomerService` already represents the business layer. Reuse terminology consistently. --- # 5. Search Before Creating Before creating: - a helper - service - repository - validator - utility - model - WSC component - framework function search for an existing implementation. Prefer extending an existing appropriate abstraction over creating duplicates. --- # 6. Make Small Changes Prefer the smallest coherent change that solves the problem. Avoid unrelated cleanup unless necessary. If a task exposes a larger architectural problem: 1. solve the requested problem safely 2. document the larger concern 3. improve the architecture when justified Do not turn every bug fix into a rewrite. --- # 7. Never Hide Errors to Make Code Appear Functional Do not use broad: ```vbscript On Error Resume Next ``` to make failures disappear. Errors should be: ```text prevented handled logged or propagated ``` Never silently swallowed. --- # 8. Security Review Is Mandatory For each change involving input, output, authentication, database access, file handling, or state changes, inspect for: ```text SQL injection XSS CSRF authorization bypass open redirects path traversal unsafe file upload sensitive logging session misuse ``` Security checks are not optional even if the user did not explicitly request them. --- # 9. SQL Generation Always prefer parameterized ADODB commands. If existing code concatenates SQL, do not copy the unsafe pattern into new code. When touching the unsafe section directly, improve it if doing so is reasonably scoped and compatibility can be preserved. --- # 10. HTML Generation Dynamic text should be HTML encoded by default. Do not output raw Request or database values into HTML. When raw HTML is intentionally supported, make that trust boundary explicit. --- # 11. Validate at the Boundary Convert raw external values into trusted application values early. Think: ```text Raw Request value ↓ Trim / normalize ↓ Required check ↓ Format validation ↓ Type conversion ↓ Business validation ↓ Use ``` Do not allow raw Request values to flow deeply through the system. --- # 12. Prefer Explicit Code In VBScript, explicit code is usually safer than clever code. Prefer: ```vbscript Dim customerId customerId = CLng(value) ``` over relying on automatic coercion. Prefer clear control flow over compressed expressions. --- # 13. Functions and Procedures Keep procedures focused. If a function performs several unrelated operations, extract meaningful collaborators. Prefer names that describe intent. Bad: ```text ProcessData HandleStuff DoWork RunThing ``` Better: ```text ValidateCustomer CalculateOrderTotal LoadCustomerById SaveAppointment ``` --- # 14. ByVal and ByRef Remember: VBScript defaults parameters to `ByRef`. When mutation is not intended, prefer: ```vbscript ByVal ``` Use `ByRef` only when caller mutation is intentional. Review changed method signatures for accidental ByRef behavior. --- # 15. Object Assignment Remember that object assignment requires `Set`. Review every new or modified object assignment. Example: ```vbscript Set service = New CustomerService ``` not: ```vbscript service = New CustomerService ``` --- # 16. Function Return Values VBScript functions return values by assigning to their own name. Review all paths. Example: ```vbscript Function IsAllowed(ByVal userId) If userId <= 0 Then IsAllowed = False Exit Function End If IsAllowed = True End Function ``` Do not accidentally leave an important return value as Empty. --- # 17. COM and ADODB Cleanup When creating: - ADODB.Connection - ADODB.Command - ADODB.Recordset - filesystem objects - external COM components understand ownership and cleanup behavior. Explicitly close database resources when appropriate. Set references to `Nothing` when ownership ends. --- # 18. Avoid Global State Prefer explicit dependencies. Do not add Session or Application state merely because it is convenient. Ask: ```text Does this value truly need to survive across requests? ``` If not, keep it request-scoped. --- # 19. Testing Strategy When possible, isolate business logic from ASP globals. Favor code that can be invoked with plain VBScript values or mock collaborators. When fixing a defect, add a regression test where practical. --- # 20. Comments Comments should explain: ```text why constraints non-obvious behavior compatibility requirements security rationale ``` Do not add comments that merely repeat the code. Bad: ```vbscript ' Set customer id customerId = 10 ``` Useful: ```vbscript ' Legacy import files use 0 to represent an unknown customer. If customerId = 0 Then ``` --- # 21. Preserve Valuable Legacy Behavior ASP Classic projects may contain old but important behavior. Do not assume unfamiliar code is wrong. Before removing or replacing something: 1. search references 2. understand callers 3. identify side effects 4. inspect related documentation 5. preserve compatibility where required --- # 22. Self-Improvement This repository is designed to allow agents to improve their own operating instructions. Self-improvement should make future work: - safer - more consistent - easier to verify - less repetitive - more maintainable Do not change instructions merely to suit the current implementation. Improve the implementation when practical rather than weakening good rules. --- # 23. Detect Learnable Events A learnable event occurs when: - a repeated bug appears - a review catches the same mistake repeatedly - a new reusable pattern proves successful - a project architecture decision becomes permanent - a new security requirement becomes necessary - a repeated workflow can be standardized - a user establishes a lasting convention - an existing instruction becomes inaccurate When a learnable event occurs, determine whether project documentation should change. --- # 24. Where Learning Should Go Use the smallest appropriate scope. Update: ```text AGENTS.md ``` for project-wide durable policies. Update: ```text CLAUDE.md ``` for agent workflow and Claude-specific operating behavior. Update: ```text /docs/* ``` for architectural or project documentation. Update: ```text /skills/* ``` for reusable specialized procedures. Update source-code comments only for code-local constraints. Do not place every lesson into AGENTS.md. --- # 25. Self-Update Decision Before modifying an instruction file, ask: ```text Is this lesson likely to matter again? ``` If no, do not persist it. Then ask: ```text Is this project-wide? ``` If yes, consider AGENTS.md. Otherwise use a specialized document. --- # 26. Never Self-Weaken Core Safety Rules Claude must not autonomously remove or weaken requirements involving: ```text Option Explicit parameterized SQL server-side authorization input validation output encoding safe error handling resource cleanup secret protection ``` If an unusual project requirement appears to conflict with one of these rules, preserve safety and document the conflict. --- # 27. Avoid Instruction Inflation Do not add a new rule for every isolated mistake. Prefer: ```text general principle + reusable example ``` rather than hundreds of hyper-specific rules. A rule should prevent a category of mistakes. --- # 28. Improve Through Abstractions Too Not every lesson belongs in documentation. If the same safety requirement appears repeatedly, consider encoding it into the framework. Examples: ```text Safe HTML helper Parameterized database wrapper Request conversion helper Validation library Authorization service Logging wrapper Repository base conventions ``` The best rule is sometimes one the architecture makes difficult to violate. --- # 29. Skill Creation Claude may create a new skill when the task is: - specialized - recurring - procedural - reusable across multiple features Possible skills: ```text /skills/asp-classic-controller.md /skills/adodb-repository.md /skills/sql-parameterization.md /skills/security-review.md /skills/vbscript-static-review.md /skills/testing.md ``` Do not create a skill for a one-time task. --- # 30. Suggested Skill Format Each skill should contain: ```text # Skill Name ## Purpose ## Use When ## Inputs ## Procedure ## Required Rules ## Validation Checklist ## Common Mistakes ## Output ## Improvement Notes ``` --- # 31. Agent Review Loop For meaningful tasks, use this cycle: ```text Understand ↓ Inspect ↓ Design ↓ Implement ↓ Review ↓ Test ↓ Learn ``` The `Learn` step asks whether the repository's instructions or abstractions should improve. --- # 32. Design Before Implementation For significant changes, identify: ```text affected layers new components existing components data flow validation boundaries security boundaries failure behavior testing strategy ``` before writing substantial code. For small tasks, keep this lightweight. --- # 33. Avoid Premature Framework Expansion Do not add framework components simply because another language would have them. ASP Classic should remain simple. Only introduce an abstraction when it solves a real recurring problem. --- # 34. Prefer Composition When extending behavior, first consider: ```text small object + small collaborator ``` instead of large pseudo-inheritance systems. VBScript is better suited to simple composition. --- # 35. Stable Public Contracts Treat established routes, APIs, class methods, and database contracts carefully. When changing them: 1. search callers 2. assess compatibility 3. update all consumers 4. document breaking changes Avoid accidental interface changes. --- # 36. Database Changes For schema changes, consider: ```text backward compatibility migration order existing data Null behavior indexes constraints application deployment timing rollback implications ``` Do not modify schema casually. --- # 37. Performance Review When working with database code, look for: ```text queries inside loops SELECT * unnecessary recordset traversal missing filters repeated connection creation large Session values unbounded result sets unnecessary COM calls ``` Prefer database-side filtering and set operations. --- # 38. Request Lifecycle Awareness Remember that ASP Classic operates per request. Avoid assumptions that local variables persist between requests. Use Session or persistent storage only when the application truly requires cross-request state. --- # 39. Application Lifecycle Awareness `Application` state is global to the ASP application. Do not store user-specific data there. Be mindful of concurrent requests. --- # 40. Avoid Hidden Dependencies A component should not unexpectedly require: ```text Request Response Session Application global connection object global logger global configuration ``` unless that dependency is part of the documented architecture. Prefer passing dependencies explicitly. --- # 41. Compatibility First During Refactoring When modernizing legacy code: ```text First preserve behavior. Then improve structure. ``` Avoid combining major behavior changes with major refactors unless necessary. --- # 42. Repository Review After Significant Changes After a meaningful feature or refactor, search for: - outdated documentation - duplicate helpers - now-dead code - inconsistent naming - old patterns replaced by the new pattern - opportunities to update an existing skill Keep the repository internally consistent. --- # 43. Learn From User Corrections If the user corrects Claude on a durable project convention, treat that as a possible learnable event. Examples: ```text "We always use this router." "Repositories never return recordsets." "All AJAX endpoints use this response format." "Use WSC components for controllers." ``` If the instruction is durable, update the appropriate project guidance. Do not persist one-time preferences as permanent architecture rules. --- # 44. Change Documentation Conservatively When modifying AGENTS.md, CLAUDE.md, or skills: - preserve useful existing rules - remove duplicates - clarify contradictions - avoid unnecessary rewrites - add an update-history entry where appropriate Instruction files should become clearer over time, not merely longer. --- # 45. Conflict Detection If project documentation contradicts itself: 1. identify the conflict 2. use higher-priority instructions 3. resolve the contradiction where safe 4. update documentation so future agents do not face the same conflict Do not silently choose different interpretations from task to task. --- # 46. Self-Improvement Is Not Autonomous Product Redesign Claude may improve: ```text guidelines skills documentation developer workflow internal abstractions ``` when justified. Claude must not independently redefine: ```text business requirements user-visible behavior pricing authorization policy data retention policy major architecture goals ``` without task requirements supporting the change. --- # 47. Final Review Mode Before completing a task, temporarily switch from implementation thinking to adversarial review. Ask: ```text How could this fail? What would VBScript fail to warn me about? What input breaks this? What happens with Null? What happens with Empty? What happens with Nothing? Did I forget Set? Could ByRef change the caller? Could SQL injection occur? Could XSS occur? Could authorization be bypassed? Could an error be swallowed? Could a recordset remain open? Did I accidentally duplicate existing functionality? ``` Fix issues found before finishing. --- # 48. Final Summary When reporting completed coding work, mention material items such as: ```text what changed important architecture choices tests performed security implications documentation or rule updates remaining limitations ``` Do not produce long explanations for trivial changes. --- # 49. Core Philosophy Claude should help make ASP Classic behave like a disciplined modern development environment without destroying the language's simplicity. The goal is not to turn VBScript into C#. The goal is to provide the safeguards that VBScript lacks. Think: ```text VBScript + clear architecture + strict conventions + reusable framework components + agent-level static analysis + continuous learning = reliable ASP Classic development ``` --- # Update History 2026-09-02 - Initial Claude operating instructions created. - Added VBScript static-review behavior. - Added controlled self-improvement workflow. - Added learnable-event detection and skill creation guidance.