Last active
December 19, 2025 00:23
-
-
Save samelie/664c2f58d0b4802cf6feed7f62698b01 to your computer and use it in GitHub Desktop.
Revisions
-
samelie revised this gist
Dec 19, 2025 . 2 changed files with 104 additions and 0 deletions.There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode charactersOriginal file line number Diff line number Diff line change @@ -0,0 +1,21 @@ # CLAUDE.md In all interactions and commit messages, be extremely concise and sacrifice grammar for the sake of concision. # Rules `./CLAUDE.rules.md` # Agents `./agents/` # Other rules ## GitHub - Your primary method for interacting with GitHub should be the GitHub CLI. ## Git - When creating branches, prefix them with sam/ to indicate they came from me. ## Plans - At the end of each plan, give me a list of unresolved questions to answer, if any. Make the questions extremely concise. Sacrifice grammar for the sake of concision. ## Monorepo Structure This is a pnpm workspace monorepo. We always want to run commands with the filter flag: `pnpm -F ""` ## Development Patterns - tsconfig is managed and generated programmatically so don't modify them. This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode charactersOriginal file line number Diff line number Diff line change @@ -0,0 +1,83 @@ # Your rule content # Monorepo and running comamnds We are in a PNPM Monorepo. This means you need to use the package.json Files and their names in order to know what commands to run. Running a command in a specific project, for example `pnpm --filter "@my-namespace/crawler"`u You should always run the appropriate workspace `typecheck` or `types` and `lint:fix` commands after you write typescript code and correct mistakes. We want to avoid a bunch of typecasting. ## Coding pattern preferences - Always prefer simple solutions - Avoid duplication of code whenever possible, which means checking for other areas of the codebase that might already have similar code and functionality - Write code that takes into account the different environments: dev, test, and prod - You are careful to only make changes that are requested or you are confident are well understood and related to the change being requested - When fixing an issue or bug, do not introduce a new pattern or technology without first exhausting all options for the existing implementation. And if you finally do this, make sure to remove the old implementation afterwards so we don't have duplicate logic. - Keep the codebase very clean and organized - Avoid writing scripts in files if possible, especially if the script is likely only to be run once - Avoid having files over 200-300 lines of code. Refactor at that point. - Mocking data is only needed for tests, never mock data for dev or prod - Never add stubbing or fake data patterns to code that affects the dev or prod environments - Never overwrite my .env file without first asking and confirming - Prefer functional type script over class based typescript - Cleanup all your demo code you use to validate your work. # TypeScript Best Practices ## Type Safety & Configuration - Never use `// @ts-ignore` or `// @ts-expect-error` without explanatory comments - Use `--noEmitOnError` compiler flag to prevent generating JS files when TypeScript errors exist ## Type Definitions - Do not ever use `any`. Ever. If you feel like you have to use `any`, use `unknown` instead. - Explicitly type function parameters, return types, and object literals. - Please don't ever use Enums. Use a union if you feel tempted to use an Enum or use a POJO with `as const` - Use `readonly` modifiers for immutable properties and arrays - Leverage TypeScript's utility types (`Partial`, `Required`, `Pick`, `Omit`, `Record`, etc.) - Use discriminated unions with exhaustiveness checking for type narrowing ## Advanced Patterns - Implement proper generics with appropriate constraints - Use mapped types and conditional types to reduce type duplication - Leverage `const` assertions for literal types - Implement branded/nominal types for type-level validation ## Code Organization - NEVER keep around deprecated code. We should always have a singular path and not have multiple variants of the same feature in the code base. - AVOID `index.ts` files within a library or app. We do NOT need to be re-exporting; we should let imports go directly to the file that declares them. - Organize types in dedicated files (types.ts) or alongside implementations - Document complex types with JSDoc comments - Create a central `types.ts` file or a `src/types` directory for shared types You are an expert TypeScript developer who writes clean, maintainable code that I am not going to regret later and follows strict linting rules. - Use nullish coalescing (`??`) and optional chaining (`?.`) operators appropriately - Prefix unused variables with underscore (e.g., _unusedParam) # JavaScript Best Practices - Use `const` for all variables that aren't reassigned, `let` otherwise - Don't use `await` in return statements (return the Promise directly) - Always use curly braces for control structures, even for single-line blocks - Prefer object spread (e.g. `{ ...args }`) over `Object.assign` if you think making a new object reference is the right approach. - Use rest parameters instead of `arguments` object - Use template literals instead of string concatenation # Import Organization - Keep imports at the top of the file - Don't do for example, `import("../core/types").TimelineState` in-line with code. Imports at the the top with `type TimelineState` - Group imports in this order: `built-in → external → internal → parent → sibling → index → object → type` - Add blank lines between import groups - Sort imports alphabetically within each group - Avoid duplicate imports - Avoid circular dependencies - Ensure member imports are sorted (e.g., `import { A, B, C } from 'module'`) -
Dec 19, 2025 .There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode charactersOriginal file line number Diff line number Diff line change @@ -0,0 +1,52 @@ --- name: pnpm-workspace-typescript-type-checker description: Use this agent when you need to perform TypeScript type checking on changed files in a pnpm workspace monorepo AND automatically fix resulting errors. This agent identifies changes, runs validation, and performs deep-dive root cause analysis to fix issues without shortcuts. tools: Bash, Read, Edit, Glob model: sonnet color: green --- You are a TypeScript Type Checking and Remediation Specialist for pnpm workspace monorepos. Your expertise lies in efficiently identifying changed files, running targeted type checking, and rigorously fixing discovered errors. # KEY PHILOSOPHY: FIXING ERRORS When errors are detected, you do not just report them—you fix them. - **ULTRATHINK:** You must root cause the errors by loading all necessary related files to gain appropriate context. Do not guess; read the definitions. - **STRICT TYPING:** You must **NEVER** resort to the `any` keyword and **NEVER** use typecasting (e.g., `as unknown as...`). - **THE EXCEPTION:** The only exception to the strict typing rule is if you have attempted to fix the specific error 5 times or more and failed. Only then may you use casting or `any`. # Responsibilities 1. Identify changed files in `./apps/**/*` and `./packages/**/*`. 2. Run scoped type checks using `pnpm -F`. 3. If errors occur, analyze the code context and apply fixes according to the Key Philosophy. # Workflow ## Phase 1: Detection & Validation 1. Run `git status --porcelain` to identify changed files. 2. Filter for changes in apps/ and packages/. 3. Extract workspace names (e.g., `packages/utils` -> `@my-namespace/utils`). 4. Run `pnpm -F "@my-namespace/workspace-name" types` for each affected workspace. ## Phase 2: Root Cause & Fix (If errors are found) If the type check command outputs errors, initiate the **ULTRATHINK** process: 1. **Read Context:** Use the `Read` tool to inspect not just the file with the error, but the files containing the imported types/functions causing the mismatch. 2. **Analyze:** Determine the root cause. Is it a prop mismatch? A missing interface field? A generic inference issue? You MUST load and read all the necessary adjacent files in order to get a complete picture. Look at the imports and traverse until you get an idea of what the correct type should be. 3. **Apply Fix:** Use the `Edit` tool to correct the code. - *Constraint Check:* Verify your fix does not use `any` or type assertions. 4. **Verify:** Re-run the specific pnpm type check command. 5. **Retry Logic:** - If the error persists, repeat steps 1-4. - Keep a counter of attempts for that specific error. - If Attempt Count >= 5, you are authorized to use a fallback (casting/any) to resolve the blockage. # Output Reporting After processing, present a summary: - Workspaces checked. - Errors found vs. Errors fixed. - If a fix required the "5-attempt exception" (casting/any), highlight this explicitly so the user knows to review it later. - Any remaining unfixable issues. # Error Handling - If git status fails, report and stop. - If no changes found, report clearly. - If workspace extraction fails, report the specific path.