agentleFS
wellwelwelwellwelwel/lagune/.claude/skills/engineering/SKILL.md

engineering

Skill216 starsChanged 16 days agoApache-2.0View on GitHub

Authoritative engineering reference covering code conventions, performance, comments, TypeScript type rules, testing, and commit messages. Use before writing or changing any source file, and when suggesting a commit message.

12 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 5 are distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 8 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Named exports only: Never use default export.

    line 26
  2. Distinctive:

    No side effects inside loops or iterations: Keep iteration pure.

    line 30
  3. Distinctive:

    Inline comments are inline for a reason: Never stack them into improvised multi-line comments.

    line 59
  4. Very specific:

    any and as unknown as are forbidden: No exceptions.

    line 64
  5. Very specific:

    Prefer type: Use interface only when a class is meant to implement it.

    line 65
  6. Very specific:

    Keep type declarations together: When the project dedicates a place to them (a types directory, for example), declare them there instead of …

    line 68
  7. Very specific:

    When the testing skill is installed, use it to decide what deserves a test and what each test must assert.

    line 72
  8. Distinctive:

    Use the runner and the scripts the project already has, and cover every runtime it supports.

    line 73
  9. Very specific:

    When the project has no runner yet, prefer Poku, and give each supported runtime its own script (for example npm test, bun run test:bun, …

    line 74
  10. Distinctive:

    Arrange, then assert: Every call and declaration comes first, then a blank line, then every assertion.

    line 76
  11. Distinctive:

    Never infer commits: Do not create a commit based on context or assumption.

    line 80

“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Engineering

This skill is the specialized, authoritative description of how code is written: the code conventions, performance, the comment discipline, the type rules, testing, and commit messages. Consult it before writing or changing source, and whenever you apply the code conventions.

Where the project already has an established convention that contradicts one below, follow the project. These rules decide whatever the project leaves open.

Code conventions

Security

  • Whenever you build or change code, use the /lagune skill (lagune.ai), named /lagune:lagune when installed as a plugin, to improve safety by default.

General

  • Arrow functions over function. Declare with const. Use a function only when the this context strictly requires it.
  • Named exports only. Never use default export.
  • No abbreviations. Names are clear and explicit (for example left/right, not a/b, and index, not i).
  • Avoid nested if-else-else-if. Favor clean, well-decoupled approaches when branching grows.
  • No duplicated logic or types. Reuse existing logic and types whenever it is viable.
  • No side effects inside loops or iterations. Keep iteration pure.
  • Make errors actionable. An error states what went wrong, where, and what was expected, so whoever reads it knows what to fix.
  • Prefer native capabilities over external dependencies whenever possible.
  • On Node.js, always prefix native imports with node: (for example node:path, node:fs).
  • Prefer the async native APIs when viable (for example node:fs/promises).

Layout

  • Shared declarations live at the top of the file or scope. Anything used by more than one block is declared before the first block that uses it, never between blocks. Order them by kind: types first, then values and fixtures, then functions.
  • Group statements by kind, and separate the groups with one blank line. Consecutive declarations stay together, consecutive calls stay together, and the switch from one kind to the other gets a blank line, even when a group holds a single statement. The same rule applies inside callbacks and between top-level declarations.

Performance

  • Maintainability comes first. Pursue performance in balance with readable code, never at its expense.
  • Keep the default path lean. An optional or uncommon feature stays behind the condition that enables it, so the default path never runs, allocates, or loads anything for it. A rare branch lives in a function of its own, so the hot function stays small enough for the engine to inline.
  • Practice early return. Handle edge cases up front, and leave a path with return, break, or continue the moment it is decided. Within a function, declare each value after the guards that can leave early, in the narrowest block that uses it, so nothing is computed or allocated for a path that never reaches it.
  • Allocate nothing a hot path can avoid. Write each value once, in place, instead of building a temporary to copy from, and allocate a collection at its final size when that size is known. A large collection lives in parallel arrays instead of one object per item, with its numbers in typed arrays.
  • Compute once. A value that cannot change between calls or iterations, such as a lookup table or a compiled pattern, is computed once, outside the function or the loop that uses it.
  • Keep shapes stable. An object a hot path touches is created with every property it will ever have, always in the same order, and never gains or loses one afterwards. Keys that change at runtime can belong in a Map.
  • Release what leaves. A structure that outlives its items drops every reference it holds to an item as soon as the item is removed, so the memory is reclaimed while the structure lives on.
  • Look up in constant time, and once. Find items through a Map or a Set instead of scanning a list inside a loop. When no stored value can be undefined, read once and test the result instead of checking for the key first.
  • Prove every optimization. A change made for performance alone is kept only when a benchmark of realistic use shows the gain over the previous version, on every runtime the project supports.

Comments

  • Never add obvious comments. Assume that if code needs a comment to be understood, the implementation is poor, dirty/messy, or even rotten.
  • The length of the comment reflects how bad the implementation is: the more explanation it needs, the worse the code.
  • Don't explain the implementation in the comments: improve the implementation (clear names, decoupled functions with clearly defined scopes, proper abstractions, etc.) over explaining it with comments.
    • Connectives betray an explanation. A comment that reads as reasoning ("so", "then", "because", "which means", "in order to", "this way", "otherwise", etc.) is walking the reader through the code, which is the violation above in disguise. Make the code carry the reasoning instead. The comment that survives states a fact the code cannot show on its own (an external constraint, a quirk, a team decision), plainly and without narrating the code around it.
    • Inline comments are inline for a reason. Never stack them into improvised multi-line comments. When one line is not enough, use a comment block, and keep it as short and direct as it can be.
  • A public API may carry documentation. What is exposed directly to the end user can have objective documentation comments stating what it does, never how it does it.

Types (TypeScript)

  • any and as unknown as are forbidden. No exceptions.
  • Prefer type. Use interface only when a class is meant to implement it.
  • No pass-through aliases. A type whose whole definition is another named type is a duplicated type under a second name.
  • Reach for as last. Prefer a direct type annotation or satisfies. A plain as cast is allowed, but only when neither of those fits.
  • Keep type declarations together. When the project dedicates a place to them (a types directory, for example), declare them there instead of scattering type and interface across the codebase.

Testing

  • When the testing skill is installed, use it to decide what deserves a test and what each test must assert.
  • Use the runner and the scripts the project already has, and cover every runtime it supports.
  • When the project has no runner yet, prefer Poku, and give each supported runtime its own script (for example npm test, bun run test:bun, deno task test:deno).
  • One blank line between tests, and between a block's setup and its first test.
  • Arrange, then assert. Every call and declaration comes first, then a blank line, then every assertion. Never interleave them. A test made only of assertions keeps them together with no blank line.

Git

  • Never infer commits. Do not create a commit based on context or assumption. Only commit when I explicitly ask for it.
  • When suggesting a commit message, treat it like a Pull Request title: a short line naming the behavior the change gives whoever uses the software, never the motivation behind it (a review, a deadline, a third party's requirement) nor its mechanics (the files, fields, or values touched). For a change that keeps the behavior, such as a refactor, name what a maintainer would notice instead. Follow Conventional Commits (e.g., type: summary, type(scope): summary):
    • ❌ fix(login): pass the accessibility audit names the motivation.
    • ❌ fix(login): remove the paste handler names the mechanics.
    • ✅ fix(login): accept pasted passwords names the behavior.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.