addin things for agents

docs/CLAUDE.md

@@ -0,0 +1,994 @@
+# 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.