fix: Simplify AGENTS.md by moving coding standards to CONTRIBUTING.md (#504)

jirispilka · web-flow · commit 0fc4d9672045 · 2026-02-27T08:33:47.000+01:00
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -186,149 +186,11 @@ Once the MCP server is configured, test the MCP tools by:
 
 ## Coding guidelines
 
-### Indentation
-
-We use **4 spaces** for indentation (configured in `.editorconfig`).
-
-### Naming conventions
-
-- **Constants**: Use uppercase `SNAKE_CASE` for global, immutable constants (e.g., `ACTOR_MAX_MEMORY_MBYTES`, `SERVER_NAME`)
-- **Functions & Variables**: Use `camelCase` format (e.g., `fetchActorDetails`, `actorClient`)
-- **Classes, Types, Interfaces**: Use `PascalCase` format (e.g., `ActorsMcpServer`, `ActorDetailsResult`)
-- **Files & Folders**: Use lowercase `snake_case` format (e.g., `actor_details.ts`, `key_value_store.ts`)
-- **Booleans**: Prefix with `is`, `has`, or `should` (e.g., `isValid`, `hasFinished`, `shouldRetry`)
-- **Units**: Suffix with the unit of measure (e.g., `intervalMillis`, `maxMemoryBytes`)
-- **Date/Time**: Suffix with `At` (e.g., `createdAt`, `updatedAt`)
-- **Zod Validators**: Suffix with `Validator` (e.g., `InputValidator`)
-
-### Types and interfaces
-
-- Prefer `type` for flexibility.
-- Use `interface` only when it's required for class implementations (`implements`).
-
-### Types organization
-
-- **Centralize shared/public types**: Put cross-module domain types and public API types in `src/types.ts`.
-- **Co-locate local types**: Keep module- or feature-specific types next to their usage (in the same file or a local `types.ts`).
-- **Use a folder-level `types.ts`** when multiple files in a folder share types, instead of inflating the root `src/types.ts`.
-
-### Comments
-
-- Use JSDoc style comments (`/** */`) for functions, interfaces, enums, and classes
-- Use `//` for generic inline comments
-- Avoid `/* */` multiline comments (single asterisk)
-- Use proper English (spelling, grammar, punctuation, capitalization)
-
-### Code structure
-
-- **Avoid `else`**: Return early to reduce indentation and keep logic flat
-- **Keep functions small**: Small, focused functions are easier to understand and test
-- **Minimal parameters**: Functions should only accept what they actually use
-  - Use comma-separated parameters for up to three parameters
-  - Use a single object parameter for more than three parameters
-- **Declare variables close to use**: Variables should be declared near their first use
-- **Extract reusable logic**: Extract complex or reusable logic into named helper functions
-- **Avoid intermediate variables for single-use expressions**: Don't create constants or variables if they're only used once. Inline them directly. For example:
-  - ❌ Don't: `const docSourceEnum = z.enum([...]); const schema = z.object({ docSource: docSourceEnum })`
-  - ✅ Do: `const schema = z.object({ docSource: z.enum([...]) })`
-  - Exception: Only create intermediate variables if they improve readability for complex expressions or serve a documentation purpose
-
-### Async functions
-
-- Use `async` and `await` over `Promise` and `then` calls
-- Use `await` when you care about the Promise result or exceptions
-- Use `void` when you don't need to wait for the Promise (fire-and-forget)
-- Use `return await` when returning Promises to preserve accurate stack traces
-
-### Imports and import ordering
-
-- Imports are automatically ordered and grouped by ESLint:
-  - Groups: builtin → external → parent/sibling → index → object
-  - Alphabetized within groups
-  - Newlines between groups
-- Use `import type` for type-only imports
-- Do not duplicate imports – always reuse existing imports if present
-- Do not use dynamic imports unless explicitly told to do so
-
-### Error handling
-
-- **User errors**: Use appropriate error codes (4xx for client errors), log as `softFail`
-- **Internal errors**: Use appropriate error codes (5xx for server errors), log with `log.exception` or `log.error`
-- Always handle and propagate errors clearly
-- Use custom error classes from `src/errors.ts` when appropriate
-- **Don't log then throw**: Do NOT call `log.error()` immediately before throwing. Errors are already logged by the caller or error handler. This creates duplicate logs and violates separation of concerns.
-  - ❌ Don't:
-    ```typescript
-    if (!indexConfig) {
-        const error = `Unknown documentation source: ${docSource}`;
-        log.error(`[Algolia] ${error}`);
-        throw new Error(error);
-    }
-    ```
-  - ✅ Do:
-    ```typescript
-    if (!indexConfig) {
-        throw new Error(`Unknown documentation source: ${docSource}`);
-    }
-    ```
-
-### Code quality
-
-- All files must follow ESLint rules (run `npm run lint` before committing)
-- Prefer readability over micro-optimizations
-- Avoid mutating function parameters (use immutability when possible)
-- If mutation is necessary, clearly document and explain it with a comment
-- Clean up temporary files, scripts, or helper files created during development
-
-### Common patterns
-
-- **Tool implementation**: Tools are defined in `src/tools/` using Zod schemas for validation
-- **Actor interaction**: Use `src/utils/apify-client.ts` for Apify API calls, never call Apify API directly
-- **Error responses**: Return user-friendly error messages with suggestions
-- **Input validation**: Always validate tool inputs with Zod before processing
-- **Caching**: Use TTL-based caching for Actor schemas and details (see `src/utils/ttl-lru.ts`)
-- **Constants and Tool Names**: Always use constants and never magic or hardcoded values. When referring to tools, ALWAYS use the `HelperTools` enum.
-  - **Exception**: Integration tests (`tests/integration/`) must use hardcoded strings for tool names. This ensures tests fail if a tool is renamed, helping to prevent accidental breaking changes.
-
-### Input validation best practices
-
-- **No double validation**: When using Zod schemas with AJV validation (`ajvValidate` in tool definitions), do NOT add additional manual validation checks in the tool implementation. The Zod schema and AJV both validate inputs before the tool is executed. Any checks redundant to the schema definition should be removed.
-  - ❌ Don't: Define enum validation in Zod, then manually check the enum again in the tool function
-  - ✅ Do: Let Zod and AJV handle all validation; use the parsed data directly in the tool implementation
-
-### Anti-patterns
-
-- **Don't** call Apify API directly – always use the Apify client utilities
-- **Don't** mutate function parameters without clear documentation
-- **Don't** skip input validation – all tool inputs must be validated with Zod
-- **Don't** use `Promise.then()` - prefer `async/await`
-- **Don't** create tools without proper error handling and user-friendly messages
-
-
-### Design System Compliance (MANDATORY)
-
-**READ FIRST**: [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md) - Complete design system rules
-
-**Quick Rules** (Zero tolerance):
-- ✅ ALWAYS use `theme.*` tokens (colors, spacing)
-- ❌ NEVER hardcode: `#hex`, `rgb()`, `Npx` values, font sizes
-- ✅ Import from `@apify/ui-library` only
-- ✅ Check `mcp__storybook__*` and `mcp__figma__*` availability before UI work
-- ✅ Call `mcp__storybook__get-ui-building-instructions` first
-- ✅ Read 1-3 similar components for patterns (max 3 files)
-- ✅ Verify zero hardcoded values before submitting
-
-**Figma Integration**: Call `mcp__figma__get_design_context` when working from designs.
-
-### What NOT to do (beyond code)
-
-- Don't add features not in the requirements
-- Don't refactor working code unless asked
-- Don't add error handling for impossible scenarios
-- Don't create abstractions for one-time operations
-- Don't optimize prematurely
-- Don't add configuration for things that won't change
-- Don't suggest "improvements" outside current task scope
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for all coding standards, common patterns, anti-patterns, and design system rules.
+
+## Branching strategy
+
+Follow [CONTRIBUTING.md](./CONTRIBUTING.md) for commit message format, PR best practices, and coding standards.
 
 ## External dependencies
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,7 +5,7 @@ All pull requests are subject to automated and manual review against these guide
 
 ---
 
-## 1. Commit Messages and PR Titles
+## Commit Messages and PR Titles
 
 All commits and PR titles must follow the **[Conventional Commits](https://www.conventionalcommits.org/)** format.
 Both the **type** (`feat`, `fix`, `chore`, etc.) and the **scope** (the component in parentheses) are required.
@@ -17,16 +17,16 @@ It applies to both commit messages and PR titles, since PRs are merged using squ
 ### Examples of Good Messages
 
 ```text
-feat: add new tool for fetching actor details
-feat!: migrate to new MCP SDK version [internal]
-fix: handle connection errors gracefully
-refactor: improve type definitions [ignore]
-chore: update dependencies
+feat: Add new tool for fetching actor details
+feat!: Migrate to new MCP SDK version [internal]
+fix: Handle connection errors gracefully
+refactor: Improve type definitions [ignore]
+chore: Update dependencies
 ```
 
 ---
 
-## 2. Pull Request Descriptions
+## Pull Request Descriptions
 
 Your PR description should extend your commit message:
 - Explain **what**, **why**, and **how**.
@@ -36,7 +36,7 @@ Your PR description should extend your commit message:
 
 ---
 
-## 3. Pull Request Comments
+## Pull Request Comments
 
 Use comments to guide reviewers:
 - Flag code that was **just moved**, so they don't re-review it.
@@ -45,14 +45,14 @@ Use comments to guide reviewers:
 
 ---
 
-## 4. Pull Request Size
+## Pull Request Size
 
 - Aim for ≤ **300 lines changed**.
 - Large PRs should be split into smaller, focused changes.
 
 ---
 
-## 5. Coding Standards & Pitfalls
+## Coding Standards & Pitfalls
 
 ### Key reminders
 *   **Keep logic flat**: avoid deep nesting and unnecessary `else`; return early instead.
@@ -139,22 +139,38 @@ Use comments to guide reviewers:
     * Prefer `type` for flexibility.
     * Use `interface` only when it's required for class implementations (`implements`).
 
+*   **Types organization:**
+    * Centralize shared/public types in `src/types.ts`.
+    * Co-locate module-specific types next to their usage (same file or a local `types.ts`).
+    * Use a folder-level `types.ts` when multiple files in a folder share types, instead of inflating the root `src/types.ts`.
+
 *   **Code Structure:**
     * Keep functions short, focused, and cohesive.
     * Declare variables close to their first use.
     * Extract reusable or complex logic into named helper functions.
+    * **Avoid intermediate variables for single-use expressions** — don't create a variable if it's only used once; inline it directly.
+        * ❌ Don't: `const docSourceEnum = z.enum([...]); const schema = z.object({ docSource: docSourceEnum })`
+        * ✅ Do: `const schema = z.object({ docSource: z.enum([...]) })`
+        * Exception: Only create intermediate variables if they improve readability for complex expressions.
 
 *   **Immutability:**
     * Avoid mutating function parameters.
     * If mutation is absolutely necessary (e.g., for performance), clearly document and explain it with a comment.
 
+*   **Imports:**
+    * Imports are ordered and grouped automatically by ESLint: builtin → external → parent/sibling → index → object, alphabetized within groups, with newlines between groups.
+    * Use `import type` for type-only imports.
+    * Do not duplicate imports — reuse existing ones.
+    * Do not use dynamic imports unless explicitly required.
+
 *   **Readability vs. Performance:**
     * Prioritize readability over micro-optimizations.
     * For performance-critical code, optimize only when justified and document the reasoning.
 
 *   **Assertions & Validations:**
     * Use **Zod** for schema-based validation of complex shapes or intricate checks.
     * Use **custom validators and assertions** for lightweight, in-code checks - e.g. validating primitive values, simple shapes, or decision logic inside functions.
+    * **No double validation:** When using Zod schemas with AJV (`ajvValidate` in tool definitions), do NOT add redundant manual validation — let the schema handle it. Use the parsed data directly.
 
 *   **Error Handling:**
     * **User Errors:**
@@ -163,6 +179,9 @@ Use comments to guide reviewers:
     * **Internal Errors:**
         * Use appropriate error codes (5xx for server errors).
         * Log with `log.exception`, `log.error`, or appropriate error logging.
+    * **Don't log then throw:** Do NOT call `log.error()` immediately before throwing — the error will be logged by the caller. This creates duplicate logs and violates separation of concerns.
+        * ❌ Don't: `log.error('Something failed'); throw new Error('Something failed');`
+        * ✅ Do: `throw new Error('Something failed');`
 
 *   **Logging:**
     * Log meaningful information for debugging, especially errors in critical system parts.
@@ -178,15 +197,53 @@ Use comments to guide reviewers:
     * Sanitize data before sending or logging.
     * Use appropriate data structures to limit exposed fields.
 
+*   **Common patterns:**
+    * **Tool implementation**: Tools are defined in `src/tools/` using Zod schemas for validation.
+    * **Actor interaction**: Use `src/utils/apify-client.ts` for Apify API calls — never call the Apify API directly.
+    * **Error responses**: Return user-friendly error messages with suggestions.
+    * **Input validation**: Always validate tool inputs with Zod before processing.
+    * **Caching**: Use TTL-based caching for Actor schemas and details (see `src/utils/ttl-lru.ts`).
+    * **Constants and tool names**: Always use constants and never hardcoded values. When referring to tools, ALWAYS use the `HelperTools` enum.
+        * Exception: Integration tests (`tests/integration/`) must use hardcoded strings for tool names. This ensures tests fail if a tool is renamed, preventing accidental breaking changes.
+
+*   **Anti-patterns:**
+    * Don't call Apify API directly — always use the Apify client utilities.
+    * Don't mutate function parameters without clear documentation.
+    * Don't skip input validation — all tool inputs must be validated with Zod.
+    * Don't use `Promise.then()` — prefer `async/await`.
+    * Don't create tools without proper error handling and user-friendly messages.
+    * Don't add features not in the requirements.
+    * Don't refactor working code unless asked.
+    * Don't add error handling for impossible scenarios.
+    * Don't create abstractions for one-time operations.
+    * Don't optimize prematurely.
+
+---
+
+## Design System Compliance (MANDATORY)
+
+**READ FIRST**: [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md) — Complete design system rules.
+
+**Quick Rules** (Zero tolerance):
+- ✅ ALWAYS use `theme.*` tokens (colors, spacing)
+- ❌ NEVER hardcode: `#hex`, `rgb()`, `Npx` values, font sizes
+- ✅ Import from `@apify/ui-library` only
+- ✅ Check `mcp__storybook__*` and `mcp__figma__*` availability before UI work
+- ✅ Call `mcp__storybook__get-ui-building-instructions` first
+- ✅ Read 1-3 similar components for patterns (max 3 files)
+- ✅ Verify zero hardcoded values before submitting
+
+**Figma Integration**: Call `mcp__figma__get_design_context` when working from designs.
+
 ---
 
-## 6. Development Setup
+## Development Setup
 
 For local development setup, scripts, and manual testing, see [DEVELOPMENT.md](./DEVELOPMENT.md).
 
 ---
 
-## 7. Code Review Guidelines
+## Code Review Guidelines
 
 - Make **two passes** on substantial PRs:
   - First: understand changes at a high level.
@@ -196,7 +253,7 @@ For local development setup, scripts, and manual testing, see [DEVELOPMENT.md](.
 
 ---
 
-## 8. Testing
+## Testing
 
 - Write tests for new features and bug fixes.
 - Ensure all tests pass before submitting a PR.
@@ -205,15 +262,15 @@ For local development setup, scripts, and manual testing, see [DEVELOPMENT.md](.
 
 ---
 
-## 9. Documentation
+## Documentation
 
 - Update README.md if adding new features or changing behavior.
 - Add JSDoc comments for public APIs.
 - Keep code comments clear and concise.
 
 ---
 
-## 10. Questions?
+## Questions?
 
 If you have questions or need help, please:
 - Open an issue for discussion
