CLAUDE.md

Agent Guidelines for Asynkron.JsEngine

Use these task-specific guides while working in the repo. MUST READ AND UNDERSTAND ALL OF THESE before working.

Standards & Architecture

• Coding standards and InvariantCulture rules
• Architecture overview

Build, Tests, and Profiling

• Use /test to run the internal test suite (not ECMAScript 262 tests)
• Build/test commands and demos
• Profiling (scripts, manual traces, hotspots)
• CPU and allocation profiling workflow
• Benchmarking and Asynkron/Jint allocation comparisons
• Recurring maintenance child runs: check active sibling summaries plus recently merged sibling work against current origin/main before choosing a slice, then report the stable evidence fields Baseline signal, Final signal, Signal delta, Sibling check, Slice check, and Scope note; use the owned operational checklist in Build/test commands and demos and durable policy in docs/rules/recurring-maintenance-child-runs.md.

Engineering Rules & Workflow

• Durable preventive rules live in docs/rules/, not .claude/rules/ (Claude Code auto-loads that folder in full and it overflows agent prompts). Scan docs/rules/README.md and read only the rule files whose scope matches your task.
• Development rules (thread safety, compliance, timeouts)
• Workflow and GitHub issue logging — GitHub issues are the persistent working memory; use Faktorial Source Context/API when supplied, otherwise use the gh CLI patterns there to view/create/comment/patch and log progress.
• Git worktree workflow
• Pre-PR checklist: Use /pre-pr skill before any PR — runs roslynator fix, tests, quickdup, format

Experimental Memory Evaluation

• Mem0 CLI is available for evaluation via the local skill at .agents/skills/mem0-cli/SKILL.md and .claude/skills/mem0-cli/SKILL.md.
• Use it only when the task explicitly needs Mem0 memory operations or the user asks to evaluate mem0/mem0-cli; GitHub issues and repo docs remain the durable project memory by default.
• Prefer structured output for agent use: rtk mem0 ... --json or rtk mem0 ... --agent.
• For evaluation setup, use agent mode such as rtk mem0 init --agent --agent-caller <agent-name> --json; never commit API keys, .env, or ~/.mem0/config.json.

JsValue and Performance Patterns

• JsValue usage and evaluator overload pattern
• Comparing to Jint (do/don't language)
• Quick ProfileRunner/Jint matrix: run rtk ./benchmark.sh for timing, rtk ./benchmark.sh --allocations for timing plus managed allocation comparison, and rtk ./benchmark.sh --smoke for the short set. See Benchmarking and Asynkron/Jint allocation comparisons.

Debugging & Test Strategies

• Debugging aids (logger assertions, slot metadata)
• Test Bomb methodology
• Layered Tests methodology

Test262 Conformance Testing

Testrunner

• The custom testrunner lives at ~/git/asynkron/Asynkron.TestRunner (global tool: testrunner)
• Run: testrunner run tests/Asynkron.JsEngine.Tests.Test262/Asynkron.JsEngine.Tests.Test262.csproj --workers 4
• Baselines: .testrunner/baseline.md — copy summary.md after each run to track progress

Crash collateral vs real failures

• The testrunner reports ~1000+ "failures" but most are crash collateral — innocent tests killed when an OOM test crashes the worker process
• Always verify failures individually: dotnet test tests/Asynkron.JsEngine.Tests.Test262 -c Release --no-build --filter "Name=<TestMethod>" --blame-hang-timeout 15s
• Real correctness failures are typically <20. Run Language and BuiltIns runsettings to get true counts:
  • dotnet test ... --settings tests/Asynkron.JsEngine.Tests.Test262/LanguageTests.runsettings
  • dotnet test ... --settings tests/Asynkron.JsEngine.Tests.Test262/BuiltInsTests.runsettings

Checking for regressions

• Before assuming a new failure is a regression, git stash and test on clean main
• Compare testrunner baselines with diff on sorted failure lists — most churn is crash collateral noise
• Excluded features (dynamic import, import-defer, etc.) are in Test262Harness.settings.json

Performance-related test failures

• RegExp property escapes, DecodeURI/EncodeURI tests are CPU-heavy — they pass individually but timeout in parallel
• Use /profile skill to profile before optimizing: dnx asynkron-profiler --cpu -- <target>
• RegexOptions.Compiled is enabled for all JS regex patterns — large patterns benefit from JIT compilation
• Property escape pattern expansions are cached via ConcurrentDictionary