16KB
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:
- Read
AGENTS.md. - Read this
CLAUDE.md. - Inspect relevant files before editing.
- Search the repository for similar implementations.
- Identify existing helpers and abstractions.
- Determine the affected architectural layers.
- Identify security-sensitive boundaries.
- 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:
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:
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:
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:
- solve the requested problem safely
- document the larger concern
- 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:
On Error Resume Next
to make failures disappear.
Errors should be:
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:
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:
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:
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:
ProcessData
HandleStuff
DoWork
RunThing
Better:
ValidateCustomer
CalculateOrderTotal
LoadCustomerById
SaveAppointment
14. ByVal and ByRef
Remember:
VBScript defaults parameters to ByRef.
When mutation is not intended, prefer:
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:
Set service = New CustomerService
not:
service = New CustomerService
16. Function Return Values
VBScript functions return values by assigning to their own name.
Review all paths.
Example:
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:
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:
why
constraints
non-obvious behavior
compatibility requirements
security rationale
Do not add comments that merely repeat the code.
Bad:
' Set customer id
customerId = 10
Useful:
' 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:
- search references
- understand callers
- identify side effects
- inspect related documentation
- 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:
AGENTS.md
for project-wide durable policies.
Update:
CLAUDE.md
for agent workflow and Claude-specific operating behavior.
Update:
/docs/*
for architectural or project documentation.
Update:
/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:
Is this lesson likely to matter again?
If no, do not persist it.
Then ask:
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:
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:
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:
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:
/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:
# 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:
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:
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:
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:
- search callers
- assess compatibility
- update all consumers
- document breaking changes
Avoid accidental interface changes.
36. Database Changes
For schema changes, consider:
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:
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:
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:
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:
"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:
- identify the conflict
- use higher-priority instructions
- resolve the contradiction where safe
- 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:
guidelines
skills
documentation
developer workflow
internal abstractions
when justified.
Claude must not independently redefine:
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:
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:
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:
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.