Skip to content

AGENTS.md

Latest commit

 

History

History
105 lines (81 loc) · 5.35 KB

AGENTS.md

File metadata and controls

105 lines (81 loc) · 5.35 KB
Raw

Agent instructions

Read this before writing anything in this repo. It applies to Claude Code, Codex, Cursor, and any other coding agent.

Writing rules

Full guide: LeagueToolkit AI styleguide. The rules that get violated most, inlined so they apply even without network access:

  • No em dashes (U+2014). Use a plain hyphen - for the parenthetical break. En dashes are fine in numeric ranges (2013–2024), just never as a sentence break.
  • No smart quotes, smart apostrophes, or the ellipsis character - ASCII ', ", and ....
  • Emoji in markdown headings are fine used sparingly, as a scanning anchor - one per heading, never on every heading, never as enthusiasm. None in code, commits, or PR titles.
  • Exclamation marks are fine for real warnings. Not for manufactured excitement ("Happy hacking!").
  • No contrast clichés ("it's not just X, it's Y"), no rule-of-three padding ("fast, reliable, and easy to use"), no hollow openers ("it's worth noting that", "let's dive in").
  • Judge vocabulary by substance, not by a blocklist. Delve, leverage, seamless, robust, comprehensive, elevate, streamline, cutting-edge, bleeding-edge, plethora: any of these is filler when it stands in for a concrete claim, and fine when a concrete claim backs it. "Bleeding-edge updates whenever the League engine changes" passes; "a robust, seamless toolkit" does not. With nothing concrete behind the word, use the plain one.
  • Bold marks one term, not half the sentence. Headings are navigation, not decoration.
  • Second person, present tense, active voice. Concrete numbers or no claim at all.
  • Say what failed. Report skipped steps and failing tests plainly; don't claim verification you didn't perform.

Accuracy

This repo deals with reverse-engineered League of Legends file formats. Invented detail is the worst failure mode available to you.

  • Never state an offset, field size, magic value, CLI flag, config key, or API signature you haven't read in this repo's source. Model priors about League formats are not evidence.
  • Label guesses as guesses. "Probably a flags field; observed values are 0 and 3."
  • Name unidentified fields unknown_0x14, with a comment on observed values. A plausible wrong name propagates into every downstream tool.
  • Don't fabricate benchmarks, versions, dates, or names.

Code

  • Match the surrounding code: naming, error handling, module layout, and comment density.
  • cargo fmt --all -- --check, cargo clippy -- -D warnings, and cargo test must pass before you call the work done.
  • Add a test with every bug fix - one that fails before the change.

Comments

  • Comment why, not what - in a line or two. A comment that reads like a design-decision writeup gets cut, not kept.
  • Open with what the thing is, not what it does or creates. The first words are a noun phrase naming the construct. "Animatable stops for the card ring", not "Registered so the ramp interpolates on hover". A comment that opens with a verb is restating the declaration beneath it in prose, and a reader who already read the declaration learns nothing.
  • Mechanism narration is not rationale. How the layers stack, what gets painted, what the browser would otherwise do - the code shows all of that. Keep the one constraint a reader would violate by accident; drop the rest.

Two comments that got this wrong

Both shipped in src/styles/custom.css. Same failure in both: usage-first opener, then a paragraph explaining the CSS properties underneath.

/* The brand ramp as the card's edge. `border-color` takes no gradient, so the
   ramp fills the border box and an opaque surface layer clipped to the padding
   box covers all of it but the 1px border ring. Both layers are painted, never
   subtracted - a hollowed-out mask leaves gaps at the corners on fractional
   device pixel ratios. The card is opaque as a result: it must sit on the page
   background, not on a tinted surface. */

/* Registered so the ramp and the fill interpolate on hover; a var() the
   browser treats as a plain token would jump between the two states. */

The first opens on a metaphor ("as the card's edge") and then narrates four declarations that are visible three lines down. The second opens on a verb about an effect. Neither tells you what the block is before telling you what it accomplishes. Rewritten:

/* Gradient border for link cards: ramp on the border box, opaque fill clipped to
   the padding box. Opaque by construction - needs the page background under it. */

/* Animatable percentage stops for the card ring and fill; plain custom properties
   would jump instead of interpolating. */

Each names its subject in the first three words, then spends its remaining budget on the single fact the code cannot show - the opacity constraint, and the reason @property is there at all.

Commits

  • Conventional Commits, imperative, lowercase after the type, under ~72 chars, no trailing period: fix: handle zero-length chunks when extracting
  • Body says why and what behavior changed. Not a file-by-file list.
  • No AI attribution trailers unless a maintainer asks for one.
  • Don't commit or push unless asked.

Repo specifics

{{TODO}}