serverlessinsight AGENTS.md

AGENTS.md - Coding Conventions for AI Agents

This document defines coding conventions that AI agents (and human developers) must follow when contributing to ServerlessInsight.

Build/Lint/Test Commands

# Build the project
npm run build

# Lint check (without fixing)
npm run lint:check

# Lint and auto-fix issues
npm run lint:fix

# Run all tests
npm test

# Run tests for a specific file pattern
npm test -- --testPathPatterns="fc3Resource" --passWithNoTests

# Run a single test file
npm test -- --testPathPatterns="path/to/test.test.ts" --passWithNoTests

# Run tests matching a test name pattern
npm test -- --testNamePattern="should create resource" --passWithNoTests

# CI test run (no debug output)
npm run test:ci

Internationalization (i18n) - MANDATORY

All user-facing messages MUST use the i18n system. Never hardcode English strings.

Pattern

1. Add the message key to src/lang/en.ts:

   YOUR_MESSAGE_KEY: 'Your message with {{variable}} placeholder',
   

2. Add the Chinese translation to src/lang/zh-CN.ts:

   YOUR_MESSAGE_KEY: '带有 {{variable}} 占位符的中文消息',
   

3. Use the message in code:

   import { lang } from '../../lang';
   
   throw new Error(lang.__('YOUR_MESSAGE_KEY', { variable: value }));
   

Examples

WRONG - Hardcoded English string:

throw new Error(`RAM role "${roleName}" does not exist in the cloud provider.`);

CORRECT - Using i18n:

import { lang } from '../../lang';

throw new Error(lang.__('RAM_ROLE_NOT_FOUND_IN_CLOUD', { roleName }));

Where this applies

• Error messages
• Warning messages
• Info/log messages
• User prompts
• Any text that could be seen by an end user

Where this does NOT apply

• Internal debug identifiers
• API request/response field names
• Code comments
• Variable/function names

Functional TypeScript

Function Style

• Define functions as const: Use const xxx = (...) => ... syntax
• Prefer functional decomposition over OOP: Avoid classes unless strictly necessary
• Keep functions small and focused: Single responsibility, easy to test