mrzmyr/pixy-mood-tracker-app / .agents/skills/coding-standards
coding-standards
VerifiedUse when writing, reviewing, or refactoring TypeScript
Coding Standards
Principles
- No backward compatibility. Remove obsolete paths instead of adding compatibility layers, fallbacks, or migrations.
- Simplest thing that fully works. Choose the simplest implementation that meets the current requirements. Avoid speculative abstractions, configuration, and indirection.
- Grow in layers. Start with the smallest version that works end to end, and add each capability on top of something that already works. Never trade a working product for unfinished complexity.
- Modular by default. Keep components separate and concerns clearly divided.
- Use existing dependencies first. Reach for what the project already has before writing your own implementation or adding a package. Do not assume a library lacks a capability without checking its docs and types.
- Prefer established libraries. Use well-maintained libraries when they reduce complexity or improve reliability. Do not reimplement common functionality without a clear reason.
- Decide for the long term. Do not accept a stopgap that only works for now and is meant to be replaced later.
Function Calls
- Prefer named parameters over positional parameters.
- Use an object argument when a function takes multiple values, optional values, or values whose meaning is not obvious from type alone.
✅ Use
getUsers({ pageSize, pageIndex });
const tool = stripPrefix({
value: ctx.toolName,
prefix: prefix,
});
❌ Avoid
getUsers(pageSize, pageIndex);
stripPrefix(ctx.toolName, prefix);
Branch Bodies
Avoid ternaries that stand in for a branch. Oxlint rejects nested ternaries; simple ternaries still need judgment.
Error Logging
Every real error path must use the project's structured error helper. This includes thrown errors, returned HTTP/OAuth/JSON errors, and error logs.
Structured errors must include:
statusmessagewhyfix
The fields must be specific enough for an operator or developer to understand what happened, why it happened, and what action resolves it.
✅ Use
throw createError({
status: 502,
message: "OAuth metadata request failed",
why: `The provider returned status ${response.status} while loading OAuth metadata`,
fix: "Verify the OAuth provider is reachable and the issuer configuration is correct",
});
❌ Avoid
throw new Error(`OAuth metadata request failed with ${response.status}`);
Boolean Names
Boolean-returning functions must be prefixed with a boolean-style verb.
Use prefixes like:
ishascanshouldwaswill
✅ Use
function isAllowed({ userId }: { userId: string }): boolean {
return userId.length > 0;
}
❌ Avoid ambiguous boolean names
function allowed(userId: string): boolean {
return userId.length > 0;
}
Function Names
Function names should be short and start with an action verb. Prefer verb + subject.
Use verbs like:
getsetcreateupdatedeletefetchloadparseformatincreasedecrease
✅ Use
getAttrs();
increaseRetries();
formatName();
❌ Avoid noun-only or abbreviated names when the function performs an action
baseAttr();
retryCount();
displayName();
✅ Use one-word function names when the word is the complete, intentional API and reads clearly at the call site, especially for small DSL-style helpers or result builders
success();
error();
text();
Local File Name Context
Use the file name as naming context. Do not repeat the domain already supplied by the file path or file name unless it removes ambiguity at the call site.
✅ Use
// data-analysis.ts
export function getSandbox() {
// ...
}
❌ Avoid
// data-analysis.ts
export function getDataAnalysisSandbox() {
// ...
}
- Prefer shorter local names when the module boundary already supplies the noun
- Use longer names only when exported APIs are commonly imported into contexts where the shorter name would be unclear
Fallbacks
- Question your usage of fallbacks (e.g. environment variables overrides).
✅ Use
const DATABASE_URL = process.env.DATABASE_URL;
if (!DATABASE_URL) {
throw createError({
status: 500,
message: "DATABASE_URL is required",
why: "DATABASE_URL was not set in the environment",
fix: "Set DATABASE_URL before starting the service",
});
}
❌ Avoid
const DATABASE_URL =
process.env.DATABASE_URL ??
process.env.LEGACY_DATABASE_URL ??
"postgres://localhost:5432/app";
Regex Pattern Matching
- Question your usage of pattern matching via regex.
✅ Use
async function readOnlyQuery({ db, query }) {
const result = await db.explainQuery({ query });
if (result.statementType !== "SELECT") {
// throw structured error
}
return query;
}
❌ Avoid
function readOnlyQuery(query) {
const sql = String(query).trim().replace(/;+\s*$/, "");
if (!/^(select|with|explain)\b/i.test(sql)) throw new Error("read only only");
if (/\b(insert|update|delete|drop|alter|create)\b/i.test(sql)) throw new Error("mutating sql");
return sql;
}
JSDoc Comments
- Oxlint enforces JSDoc presence on exported declarations.
- You must write a JSDoc comment for each public method and each public property of an exported class.
- Write the JSDoc comment on the original declaration. Do not write a JSDoc comment for a re-export.
- Write a JSDoc comment for internal code only when the code is complex.
- Write the invariant, the limitation, or the constraint that the TypeScript types cannot show.
- Do not describe how the code operates. Do not write the TypeScript types again in the comment. Do not use
@inheritDocor@inherit. - In the
@returnstag, write the typed errors that the function can return. These errors includeResulttypes and tagged errors. - Use the
@throwstag only if one of these is true:- The throw shows a defect that the program cannot correct.
- The framework makes the throw necessary.
- The path is a temporary
notYetImplementedpath.
- Write a JSDoc comment for each field of a complex object type that you export.
✅ Good
/**
* Parse an email address from untrusted input.
*
* The input is trimmed and lower-cased before validation. Construct values
* only through this function; the brand makes raw strings unusable where an
* {@link EmailAddress} is required.
*
* @param input - The untrusted string to parse.
* @returns A parsed {@link EmailAddress}, or {@link InvalidEmailAddress} when
* the input is invalid.
*/
export function parse(input: string): Result<EmailAddress, InvalidEmailAddress> {
// ...
}
/** Input required to evaluate a boolean flag for a single user. */
export type BooleanFlagInput = {
/** The feature flag key to evaluate. */
readonly flagKey: string;
/** The user's email, used as both context key and email attribute. */
readonly userEmail: string;
/** The value returned when the flag cannot be evaluated. */
readonly defaultValue: boolean;
};
❌ Bad
/**
* Parses input.
*
* @inheritDoc
* @param input - string
* @returns Result<EmailAddress, InvalidEmailAddress>
*/
export function parse(input: string): Result<EmailAddress, InvalidEmailAddress> {
// ...
}
export type BooleanFlagInput = {
readonly flagKey: string;
readonly userEmail: string;
readonly defaultValue: boolean;
};
Comments on Edge Cases
- When fixing edge cases, add a comment explaining and add links to the relevant documentation.
✅ Good
/**
* Context window of {@link MODEL_ID}. Declared here because this model is
* unlisted in the gateway catalog, so the build cannot resolve compaction
* metadata. Keep it in sync when the model changes.
* See https://example.com/docs/agent-config
*/
export const MODEL_CONTEXT_WINDOW_TOKENS = 1_000_000;
❌ Bad
export const MODEL_CONTEXT_WINDOW_TOKENS = 1_000_000;
✅ Good
/**
* Terminal assistant message held until the turn ends.
*
* `message.completed` fires inside the step that produced it, before that
* step's `step.completed` reports usage. Posting there would render a footer
* whose cost is always missing on a single-step turn, so delivery waits for
* `turn.completed`. See https://example.com/docs/sessions
*/
const pendingChannelResponse = defineState<PendingChannelResponse | null>(
"my-agent.pending-channel-response",
() => null,
);
❌ Bad
const pendingChannelResponse = defineState<PendingChannelResponse | null>(
"my-agent.pending-channel-response",
() => null,
);
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |