Agent Guidelines

This document contains my coding guidelines and best practices for software projects. It is meant to be general purpose and should be a starting point. If any guidelines here conflict with a project's specific guidelines, then the project's specific guidelines should take precedence.

Baseline Principles

Security

Write secure code.

Javascript

write modern javascript
use ESM (no commonjs) whether in browser or node
use latest LTS version of node (currently 24.11.0)

Coding conventions

write pure functions when possible
Prefer iteration and modularization over code duplication.

Frontend Development Guidelines

Project Structure

unless otherwise specified, frontend projects should have the following structure:
- should have a frontend folder at the root of the project
  - this contains the frontend code that will be built with eleventy SSG
  - any static/non-interactive (marketing/content) pages will be generated at built-time using webc
  - any dynamic pages (where contents are different for each user) should have the page built with webc (that will contain the <head> since it's usually shared across pages) and then the body of the page be a LIT component that will be hydrated on the client-side
- should have a backend folder at the root of the project
  - this will contain serverless functions that will provide the backend API to the frontend
  - we will use cloudflare workers for the backend
- should have a scripts folder at the root of the project
  - this will contain any scripts the project needs (build scripts, deployment scripts, etc.)

Eleventy URL Structure

Always use trailing slashes when constructing URLs for Eleventy-based projects
Eleventy generates routes with trailing slashes (e.g., /medication/ instead of /medication)
When constructing URLs programmatically (e.g., window.location.href, redirects), always include the trailing slash before query parameters
Example: Use /medication/?id=123 instead of /medication?id=123 to avoid 301 redirects that strip query parameters
This matches Cloudflare Pages' preferred URL structure and prevents redirect issues in both development and production

head component example

<!-- frontend/_components/page-head.webc -->
<head webc:is="fw-head" webc:nokeep>
  <meta charset="UTF-8" />
  <title @text="title"></title>
  <link rel="icon" href="/logo.svg" />
  <link rel="apple-touch-icon" href="/logo-180.png" />
  <meta
    name="viewport"
    content="width=device-width, initial-scale=1, viewport-fit=cover"
  />
  <meta name="description" :content="description" />
  <link rel="manifest" href="/app.webmanifest" />

  <!-- Control the behavior of search engine crawling and indexing -->
  <!-- All Search Engines -->
  <meta name="robots" content="index,follow" />

  <!-- Helps prevent duplicate content issues -->
  <link rel="canonical" :href="canonical" />

  <!-- Facebook Open Graph meta -->
  <meta property="og:url" :content="canonical" />
  <meta property="og:type" content="website" />
  <meta property="og:title" :content="title" />
  <meta property="og:image" :content="og_image" />
  <meta property="og:description" :content="description" />
  <meta property="og:site_name" :content="title" />
  <meta property="og:locale" content="en_US" />

  <script
    src="https://cdn.usefathom.com/script.js"
    defer
    :data-site="fathom_site_id"
    webc:keep
  ></script>

  <script type="module">
    navigator.serviceWorker.register("/sw.js");
  </script>
</head>

// frontend/_data/site.js
const url = "https://app-url-here.com";

export default {
  title: "My App",
  description: "My App description here",
  url,
  canonicalUrl: `${url}/`,
  copyrightName: "My App",
  isProdEnv: process.env.ELEVENTY_ENV === "production",
  fathom_site_id: "my-fathom-site-id-here",
  currentYear: new Date().getFullYear(),
  build_time: new Date().toISOString(),
};

<!-- frontend/includes/layout.webc -->
<html lang="en">
  <head>
    <meta
      webc:is="page-head"
      :title="page.title || site.title"
      :description="page.description || site.description"
      :fathom_site_id="site.fathom_site_id"
      :canonical="site.url + page.url"
    />

    <!-- inline the webc component styles -->
    <style @raw="getBundle('css')" webc:keep></style>
    <!-- inline the webc component js -->
    <script type="module" @raw="getBundle('js')" webc:keep></script>

    <!-- other stuff -->
  </head>
</html>

Hosting

We will use cloudflare workers for hosting. The frontend will be static assets served from cloudflare workers, and the backend will be serverless functions served from cloudflare workers.

Web development

if you can build something with HTML and CSS, favor doing that over using javascript
use progressive enhancements as often as possible
Use modern CSS for styling (no preprocessors, no frameworks, no css-in-js)
Use grid and flexbox for layout
use semantic elements when possible, only use divs and spans when there is no other semantically-appropriate element. Avoid semanticless divs - prefer elements like <header>, <nav>, <main>, <article>, <section>, <aside>, <footer>, <form>, etc. when they semantically match the content.
when using input elements, always wrap them in a <form> element for proper semantics and accessibility. This ensures proper form submission behavior, keyboard navigation, and screen reader support.
prefer nested css selectors, element and ID selectors over class selectors. For example, instead of <header><h1 class="title">The title</h1></header>, use <header><h1>The title</h1></header> and then use a selector like header { & h1 { ... } } instead of .title { ... }. Because if we are writing accessible, semantic HTML then there is only one h1 in the header.

Page structure pattern: Most pages should wrap their content in a <main> element, and nest all CSS rules under main using the & prefix. Use element selectors and IDs (for unique elements) rather than classes. Only use classes when an element appears multiple times or styling is meant to be reusable. Example:

<main>
  <header>
    <h1>Page Title</h1>
  </header>
  <section id="content">
    <p>Content here</p>
  </section>
</main>

main {
  max-width: 800px;
  margin: 0 auto;

  & header {
    margin-bottom: 2rem;

    & h1 {
      font-size: 2rem;
    }
  }

  & #content {
    line-height: 1.6;
  }
}

avoid inline styles in html, figure out a proper selector and use that to select and style the element.
For a card component: use an article element. And instead of using div class="footer" in the card,use a <footer> element. Same for the header, use a <header> element. For the body use a <section> element.
if you can't write a selector based on an element tag, you can use an ID if that element is unique inside the shadow root of that component.
use REM over pixels for font sizes and spacing.

Dependencies

Avoid bundlers like Vite, Webpack, etc. Modern browsers support import maps, so if we do have any runtime dependencies then we'll use import maps to load them.
if we need the types of a dependency then add it as a devDependency to make it clear the version in node_modules is not a runtime dependency (ie: it's not bundled)

Data Flow Guidelines

Pages are responsible for fetching data and passing it down to components as props.
All data fetching should be client-side (CSR) unless explicitly stated otherwise.
Components should not fetch data themselves, except for truly self-contained UI widgets.

Typescript Best Practices

General

we are writing runtime code with javascript, not typescript
we still want typing, so we are using jsdoc comments to type the code
use // @ts-check at the top of the file to enable type-checking in .js files
use @typedef, @param, @returns, and @type annotations to express types in JSDoc
infer types where possible. Only add explicit types (e.g. @type {string[]}) when inference is not obvious
put shared types/interfaces in .d.ts files. Data models are an example of a shared type
we can import types from .d.ts files into our code with jsdoc comments, like this:

/** @import { User } from '../../models/User' */

Lit components

when using lit as a dependency add it as a devDependency for typing at DX time, and use an import map "lit": "https://cdn.jsdelivr.net/gh/lit/dist@3.3.1/core/lit-core.min.js" to load it at runtime.
declare properties in the static properties object, and then set their default value and type in the class with field initializers, like this:

static properties = {
	page_name: { type: String },
    stuff: {type: Array<string>},
    some_state {type: String, state: true}
};

/** @type {string} */
page_name = 'new/edit';
/** @type {string[]} */
stuff = [];
/** @type {string} */
some_state = 'initial';

export class MyThing extends LitElement {
  // ...
}

if (!customElements.get("my-thing")) {
  customElements.define("my-thing", MyThing);
}

Private Class Members

Use the # prefix for private class fields and methods
Keep implementation details hidden within the class

Async/Await Patterns

Use async/await consistently for all asynchronous operations
Properly handle promise chains with appropriate error handling

Type Assertions and Transformations

Avoid any type completely - never use any in production code
Minimize type assertions - prefer proper typing over assertions
Avoid as unknown as T - this pattern indicates poor type design
Type assertions in tests only when necessary - prefer proper mocking over assertions
Use proper interfaces over transformations - design types to match actual usage
Replace complex transformations with simplified interfaces - only include properties you actually use
Use T[] instead of Array<T> - follow consistent array type syntax
Nullable types over empty object assertions - use Type | null instead of {} as Type

Testing Guidelines

UI Testing

Use Playwright for E2E and integration testing of pages and components.
Test user flows, accessibility, and rendering.
Keep ui tests in the same directory as the component or page they are testing (e.g. pages/list.js -> pages/list.ui.test.js).
Name ui tests *.ui.test.js.
When writing locators follow the Playwright Locator Docs - try to use a11y selectors (getByRole, getByLabelText, getByPlaceholder, etc.).
- If you can't use a11y selectors, double check if the production code is properly semantic and accessible.
when validating text prefer a locator with that text ".toBeVisible()" over a locator without the text ".toContainText()". For example, await expect(page.getByRole('heading')).toContainText('New solution'); should be await expect(page.getByRole('heading', { name: "New solution" })).toBeVisible();.
Do not use waitForTimeout in tests. Playwright has implicit waits built into all locator logic. Instead of arbitrary timeouts, wait for the expected UI state changes (e.g., wait for a specific element to appear, text to change, or button state to update). This makes tests more reliable and faster.
Any tests that require time/date modification should leverage playwright's built in clock API - https://playwright.dev/docs/clock

Non-UI Testing

This applies to both non-UI client-side code and backend code. This includes unit/functional tests and scenario-based tests.

Use the Node.js built-in test runner (node:test) for non-ui tests.
Keep tests close to the file being tested when possible.
Name tests *.test.js.
Unit/functional (non-E2E) tests should be colocated next to the file being tested, named filename.test.js.",
Higher-level or scenario-based tests should be placed under a tests-e2e/ folder at the highest common ancestor of the files being tested.
Use import/export (ESM) syntax — no CommonJS.
Use assert, assert.strictEqual, and similar functions from Node's built-in assert module.
Group tests using test() and describe() blocks from node:test.
Avoid any dependency on external test runners (like Jest, Mocha, etc).
Any tests that require time/date modification should leverage node test runner's built in time mocking - https://nodejs.org/api/test.html#timers

Example

If there is a file sum.js with the following code:

/**
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
export function sum(a, b) {
  return a + b;
}

Then we want our test next to in the same directory, named sum.test.js with the following code:

import { test } from "node:test";
import assert from "node:assert";
import { sum } from "./sum.js";

test("sum", () => {
  assert.strictEqual(sum(1, 2), 3);
});

Data Dependencies

Use mock API response data for testing (we will not be making real network calls to fetch data).

Test Fixtures

create test fixtures in the __fixtures__ directory.
anytime you are mocking happy-path API responses, create a fixture for that response.
any time you are mocking edge cases, use the existing happy-path fixture as a starting point and modify in the test as needed. That way we have fixtures for happy-path cases but edge cases (which there can be a lot of permutations of edge cases) have their edge-case-response-shapes right there in the test.
- example: const response_with_no_highlights = {...test_response_from_fixture, highlights: []}
if multiple tests need the same inline fixture then create a const under the describe block and use that const in the test.

Best Practices

Write tests for happy paths and error states.
For components, test:
- Rendering with various props
- Interaction events
- Visual state changes

Code Comments Guidelines

General

For public functions/classes, use JSDoc comments so consumers can know what the function/class does and when they should use it.

When to Add Comments

Complex business logic: explain context and WHY something is done, not WHAT is done
Non-obvious edge cases: clarify unusual behavior or special handling
Architectural decisions: explain design choices that aren't obvious
Workarounds: document temporary solutions and their reasons

When NOT to Add Comments

Obvious functionality: don't comment what the code clearly shows
Test descriptions: test names and assertions should be self-explanatory
Type information: types should be self-documenting

Comment Quality Standards

Keep comments up to date: remove outdated comments immediately
Be concise and complete: provide enough context without verbosity

Code Style

Style & Naming Conventions

Use snake_case for variables, methods, and properties
Use PascalCase for classes, interfaces, and types
Use lowercase with dashes for directories (e.g., components/auth-wizard).
Use verbose names for variables, functions, and comments
Interfaces should reflect their purpose (e.g., SolutionFilter)
Methods/Functions should be verbs (e.g., get_solutions)
Classes should be nouns (e.g., ListPage)
Constants should be uppercase (e.g., MAX_SOLUTIONS)
Variables should be lowercase (e.g., max_solutions)
Properties should be nouns (e.g., max_solutions)
Prefer const and let over var.

Function Structure

Keep functions focused on a single responsibility
If a class method can be a pure function, make it a pure static function (easily unit testable)
Extract complex logic into well-named helper functions
Use early returns for validation and error conditions
Limit function complexity and length

Eleventy Project Guidelines

Only apply these guidelines to projects that are built with Eleventy.

use webc as templating language (as opposed to nunjucks or liquid)
write the 11ty config as an ESM (not commonjs)
build static/non-interactive components as webc components, build-time/template javascript is fine to use
- when doing this don't use webc scoped styling, use declarative shadow DOM in the html template to scope styles to the component.
- Define logic in <script webc:setup> and render with <template webc:root>
- when importing third-party web components (ex: lite-youtube) use <script webc:keep> to tell webc to keep the script tag around after build-time
if a component has dynamic data (that might change at runtime or be different for each user) then build the component as a LIT component, SSR it during bulid-time, and then hydrate it on the client-side.
- use https://github.com/lit/lit/tree/main/packages/labs/eleventy-plugin-lit for this
- LIT ssr only supports setting attributes, so when going from a webc page to a LIT component and you need to pass a non-scalar value (ex: an object) then you'll need to stringify it in an attribute on the lit component, which will then need to parse it in the render method. Ideally try to avoid this by breaking down objects into scalar values and passing them as attributes.

Webc quirks

you can't access props in the webc:setup script unfortunately. You have to use the _(this) function to access the props.

Example of accessing props in the webc:setup script

<script webc:setup>
  // @ts-check

  /** @typedef Props
   * @prop {string} name The name of the setting from settings.js
   */

  /**
   * @param {Props} props
   */
  function _(props) {
    // @ts-ignore - settings is available at build time
    const setting = settings[props.name];
    if (!setting) {
      throw new Error(`Setting "${props.name}" not found in settings.js`);
    }

    return {
      storage_key: setting.storage_key,
      label: setting.label,
      default_value: setting.default_value,
    };
  }
</script>

<fw-setting-toggle
  :data-storage-key="_(this).storage_key"
  :data-default-value="_(this).default_value"
  :data-label="_(this).label"
>
  <label>
    <input
      type="checkbox"
      :data-storage-key="_(this).storage_key"
      :checked="_(this).default_value"
    />
    <span id="label" @text="_(this).label"></span>
  </label>
</fw-setting-toggle>

Pull Request Guidelines

Title

The PR title MUST follow Conventional Commit format: (optional scope): short, imperative description

Allowed types:

feat
fix
chore
docs
refactor
test
ci
build

Examples:

feat(auth): add passwordless login
fix(cache): prevent stale responses
chore(deps): bump vite to 5.1
The PR title type should be inferred from the primary change:
- User-facing behavior → feat or fix
- Internal refactors → refactor
- Dependency or tooling changes → chore
- Tests only → test
- Documentation only → docs
always squash and merge PRs, use the PR title as the commit message and leave the body empty.

Commits

run npm run format:fix to format the code before making a commit.