Skip to content

Instantly share code, notes, and snippets.

@scpedicini

scpedicini/AGENTS.md

Last active May 30, 2026 03:11
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save scpedicini/1407c776b82945b723199a91ad8b1f82 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save scpedicini/1407c776b82945b723199a91ad8b1f82 to your computer and use it in GitHub Desktop.
Download ZIP
Personal AGENTS.md for LLMs (JS/TS Example)
Raw
AGENTS.md

Code Standards

  • Prefer types over interfaces for simple data structures
  • Use interfaces and class OOP for more complex components
  • Comments should be used to explain "why" decisions were made with possible source references
  • Avoid magic numbers or strings - use constants instead, and if they feel like configuration values, move them to a configuration file
  • Avoid default parameter values especially in method signatures since this can lead to unexpected behavior. For example if a method signature has three arguments, then a caller is required to pass in exactly three arguments.
  • Avoid null coalescing (??) or fallbacks. All values should always be explicitly set.
  • Avoid default parameters / default fallbacks / etc. since this silently obfuscates errors. Errors should always propagate so we can discover potential issues.

Documentation

  • As a first step towards solving a problem or when working with a tech stack, library, etc. always check for any related documentation under the ./docs directory.

UI Notes

  • Remember to account for both mobile and desktop views since there may be different visual components for each.
  • Always use both visual and DOM inspection: When diagnosing frontend issues, take a visual screenshot AND run JavaScript to inspect/check the DOM (e.g., browser_evaluate to check computed styles, element dimensions, classes).
  • Check the dev tools console for errors or warnings that may indicate issues with rendering, assets, or scripts.
  • No layout shifts: Buttons and UI elements must maintain consistent dimensions when their content changes (e.g., "Solve" → "Solving...", "Stop"). Use fixed widths, min-width, or reserve space for the longest possible text.

Tests

Whenever a change or addition is made, you are required to add comprehensive new unit, integration, and E2E tests to ensure code quality and prevent regressions. Adding E2E should use playwright. Whenever you finish fixing a bug you must also write an accompanying unit, integration, or E2E test that would have caught the bug.

Final Notes

Whenever you finish a task you must perform the following in order:

  • Run the tests to ensure all new and existing tests pass.
  • Run pnpm run check to ensure code is properly formatted and linted.
  • Run pnpm run build to ensure the project builds successfully.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment