whale-town-end/docs/ai-reading

AI Code Inspection Guide - Whale Town Game Server

🎯 Pre-execution Setup

🚀 User Information Setup

Before starting any inspection steps, run the user information script:

# Enter AI-reading directory
cd docs/ai-reading

# Run user information setup script
node tools/setup-user-info.js

Script Functions

• Automatically get current date (YYYY-MM-DD format)
• Check if config file exists or date matches
• Prompt for username/nickname input if needed
• Save to me.config.json file for AI inspection steps

Config File Format

{
  "date": "2026-01-13",
  "name": "Developer Name"
}

📋 Using Config in AI Inspection Steps

When AI executes inspection steps, get user info from config file:

// Read config file
const fs = require('fs');
const config = JSON.parse(fs.readFileSync('docs/ai-reading/me.config.json', 'utf-8'));

// Get user information
const userDate = config.date;  // e.g.: "2026-01-13"
const userName = config.name;  // e.g.: "John"

// Use for modification records and @author fields
const modifyRecord = `- ${userDate}: Code standard optimization - Clean unused imports (Modified by: ${userName})`;

🏗️ Project Characteristics

This project is a NestJS Game Server with the following features:

• Dual-mode Architecture: Supports both database and memory modes
• Real-time Communication: WebSocket-based real-time bidirectional communication
• Property Testing: Admin modules use fast-check for randomized testing
• Layered Architecture: Core layer (technical implementation) + Business layer (business logic)

🔄 Execution Principles

🚨 Mid-step Start Requirements (Important)

If AI starts execution from any intermediate step (not starting from step 1), must first complete the following preparation:

📋 Mandatory Information Collection

Before executing any intermediate step, AI must:

1. Collect user current date: For modification records and timestamp updates
2. Collect user name: For @author field handling and modification records
3. Confirm project characteristics: Identify NestJS game server project features

🔍 Global Context Acquisition

AI must first understand:

• Project Architecture: Dual-mode architecture (database+memory), layered structure (Core+Business)
• Tech Stack: NestJS, WebSocket, Jest testing, fast-check property testing
• File Structure: Overall file organization of current project
• Existing Standards: Established naming, commenting, testing standards in project

🎯 Execution Flow Constraints

Mid-step Start Request
    ↓
🚨 Mandatory User Info Collection (date, name)
    ↓
🚨 Mandatory Project Characteristics & Context Identification
    ↓
🚨 Mandatory Understanding of Target Step Requirements
    ↓
Start Executing Specified Step

⚠️ Violation Handling: If AI skips information collection and directly executes intermediate steps, user should require AI to restart and complete preparation work.

⚠️ Mandatory Requirements

• Step-by-step Execution: Execute one step at a time, strictly no step skipping or merging
• Wait for Confirmation: Must wait for user confirmation after each step before proceeding
• Modification Verification: Must re-execute current step after any file modification
• 🔥 Must Re-execute Current Step After Modification: If any modification behavior occurs during current step (file modification, renaming, moving, etc.), AI must immediately re-execute the complete check of that step, cannot directly proceed to next step
• Re-check After Problem Fix: If current step has problems requiring modification, AI must re-execute the step after solving problems to ensure no other issues are missed
• User Info Usage: All date fields use user-provided real dates, @author fields handled correctly

🎯 Execution Flow

User Requests Code Inspection
    ↓
Collect User Info (date, name)
    ↓
Identify Project Characteristics
    ↓
Execute Step 1 → Provide Report → Wait for Confirmation
    ↓
[If Modification Occurs] → 🔥 Immediately Re-execute Step 1 → Verification Report → Wait for Confirmation
    ↓
Execute Step 2 → Provide Report → Wait for Confirmation
    ↓
[If Modification Occurs] → 🔥 Immediately Re-execute Step 2 → Verification Report → Wait for Confirmation
    ↓
Execute Step 3 → Provide Report → Wait for Confirmation
    ↓
[If Modification Occurs] → 🔥 Immediately Re-execute Step 3 → Verification Report → Wait for Confirmation
    ↓
Execute Step 4 → Provide Report → Wait for Confirmation
    ↓
[If Modification Occurs] → 🔥 Immediately Re-execute Step 4 → Verification Report → Wait for Confirmation
    ↓
Execute Step 5 → Provide Report → Wait for Confirmation
    ↓
[If Modification Occurs] → 🔥 Immediately Re-execute Step 5 → Verification Report → Wait for Confirmation
    ↓
Execute Step 6 → Provide Report → Wait for Confirmation
    ↓
[If Modification Occurs] → 🔥 Immediately Re-execute Step 6 → Verification Report → Wait for Confirmation
    ↓
Execute Step 7 → Provide Report → Wait for Confirmation
    ↓
[If Modification Occurs] → 🔥 Immediately Re-execute Step 7 → Verification Report → Wait for Confirmation

⚠️ Key Rule: After any modification behavior in any step, must immediately re-execute that step!

📚 Step Execution Guide

Step 1: Naming Convention Check

Read when executing: step1-naming-convention.md Focus on: Folder structure flattening, game server special file types After completion: Provide inspection report, wait for user confirmation

Step 2: Comment Standard Check

Read when executing: step2-comment-standard.md Focus on: @author field handling, modification record updates, timestamp rules After completion: Provide inspection report, wait for user confirmation

Step 3: Code Quality Check

Read when executing: step3-code-quality.md Focus on: TODO item handling, unused code cleanup After completion: Provide inspection report, wait for user confirmation

Step 4: Architecture Layer Check

Read when executing: step4-architecture-layer.md Focus on: Core layer naming standards, dependency relationship checks After completion: Provide inspection report, wait for user confirmation

Step 5: Test Coverage Check

Read when executing: step5-test-coverage.md Focus on: Strict one-to-one test mapping, test file locations, test execution verification After completion: Provide inspection report, wait for user confirmation

🧪 Test File Debugging Standards

When debugging test files, must follow this workflow:

1. Read jest.config.js Configuration

   • Check jest.config.js to understand test environment configuration
   • Confirm testRegex patterns and file matching rules
   • Understand moduleNameMapper and other configuration items

2. Use Existing Test Commands in package.json

   • Forbidden to customize jest commands: Must use test commands defined in package.json scripts
   • Common Test Commands:
     • npm run test - Run all tests
     • npm run test:unit - Run unit tests (.spec.ts files)
     • npm run test:integration - Run integration tests (.integration.spec.ts files)
     • npm run test:e2e - Run end-to-end tests (.e2e.spec.ts files)
     • npm run test:watch - Run tests in watch mode
     • npm run test:cov - Run tests and generate coverage report
     • npm run test:debug - Run tests in debug mode
     • npm run test:isolated - Run tests in isolation

3. Specific Module Test Commands

   • Zulip Module Tests:
     • npm run test:zulip - Run all Zulip-related tests
     • npm run test:zulip:unit - Run Zulip unit tests
     • npm run test:zulip:integration - Run Zulip integration tests
     • npm run test:zulip:e2e - Run Zulip end-to-end tests
     • npm run test:zulip:performance - Run Zulip performance tests

4. Test Execution Verification Workflow

   Discover Test Issue → Read jest.config.js → Choose Appropriate npm run test:xxx Command → Execute Test → Analyze Results → Fix Issues → Re-execute Test
   

5. Test Command Selection Principles

   • Single File Test: Use npm run test -- file_path
   • Specific Type Test: Use corresponding test:xxx command
   • Debug Test: Prioritize npm run test:debug
   • CI/CD Environment: Use npm run test:isolated

Step 6: Function Documentation Generation

Read when executing: step6-documentation.md Focus on: API interface documentation, WebSocket event documentation After completion: Provide inspection report, wait for user confirmation

Step 7: Code Commit

Read when executing: step7-code-commit.md Focus on: Git change verification, modification record consistency check, standardized commit process After completion: Provide inspection report, wait for user confirmation

📋 Unified Report Template

Use this template for reporting after each step completion:

## Step X: [Step Name] Inspection Report

### 🔍 Inspection Results
[List of discovered issues]

### 🛠️ Correction Plan  
[Specific correction suggestions]

### ✅ Completion Status
- Check Item 1 ✓/✗
- Check Item 2 ✓/✗

**Please confirm correction plan, proceed to next step after confirmation**

🚨 Global Constraints

📝 File Modification Record Standards (Important)

After each modification execution, file headers need to update modification records and related information

Modification Type Definitions

• Code Standard Optimization - Naming standards, comment standards, code cleanup, etc.
• Feature Addition - Adding new features or methods
• Feature Modification - Modifying existing feature implementations
• Bug Fix - Fixing code defects
• Performance Optimization - Improving code performance
• Refactoring - Code structure adjustment but functionality unchanged

Modification Record Format Requirements

/**
 * Recent Modifications:
 * - [User Date]: Code Standard Optimization - Clean unused imports (Modified by: [User Name])
 * - 2024-01-06: Bug Fix - Fix email validation logic error (Modified by: Li Si)
 * - 2024-01-05: Feature Addition - Add user verification code login feature (Modified by: Wang Wu)
 * 
 * @author [Processed Author Name]
 * @version x.x.x
 * @since [Creation Date]
 * @lastModified [User Date]
 */

🔢 Recent Modification Record Quantity Limit

• Maximum 5 Records: Recent modification records keep maximum of 5 latest records
• Auto-delete When Exceeded: When adding new modification records, if exceeding 5, automatically delete oldest records
• Maintain Time Order: Records arranged in reverse chronological order, newest at top
• Complete Record Retention: Each record must include complete date, modification type, description and modifier information

Version Number Increment Rules

• Patch Version +1: Code standard optimization, bug fixes (1.0.0 → 1.0.1)
• Minor Version +1: Feature addition, feature modification (1.0.1 → 1.1.0)
• Major Version +1: Refactoring, architecture changes (1.1.0 → 2.0.0)

Time Update Rules

• Check Only No Modification: If only checking without actually modifying file content, do not update @lastModified field
• Update Only on Actual Modification: Only update @lastModified field and add modification records when actually modifying file content
• Git Change Detection: Check if files have actual changes through git status and git diff, only add modification records and update timestamps when git shows files are modified

🚨 Important Emphasis: Pure Check Steps Do Not Update Modification Records

When AI executes code inspection steps, if code already meets standards and needs no modification, then:

• Forbidden to Add Modification Records: Do not add records like "AI code inspection step X: XXX check and optimization"
• Forbidden to Update Timestamps: Do not update @lastModified field
• Forbidden to Increment Version Numbers: Do not modify @version field
• Only add modification records when actually modifying code content, comment content, structure, etc.

Wrong Example:

// ❌ Wrong: Only checked without modification but added modification record
/**
 * Recent Modifications:
 * - 2026-01-12: Code Standard Optimization - AI code inspection step 2: Comment standard check and optimization (Modified by: moyin)  // This is wrong!
 * - 2026-01-07: Feature Addition - Add user verification feature (Modified by: Zhang San)
 */

Correct Example:

// ✅ Correct: Check found compliance with standards, do not add modification records
/**
 * Recent Modifications:
 * - 2026-01-07: Feature Addition - Add user verification feature (Modified by: Zhang San)  // Keep original records unchanged
 */

@author Field Handling Standards

• Retention Principle: Human names must be retained, cannot be arbitrarily modified
• AI Identifier Replacement: Only AI identifiers (kiro, ChatGPT, Claude, AI, etc.) can be replaced with user names
• Judgment Example: @author kiro → Can replace, @author Zhang San → Must retain

Game Server Special Requirements

• WebSocket Files: Gateway files must have complete connection and message processing tests
• Dual-mode Services: Both memory services and database services need complete test coverage
• Property Testing: Admin modules use fast-check for property testing
• Test Separation: Strictly distinguish unit tests, integration tests, E2E tests, performance tests

🔧 Modification Verification Process

🔥 Immediately Re-execute Rule After Modification (Important)

After any modification behavior occurs in any step, AI must immediately re-execute that step, cannot directly proceed to next step!

Modification Behaviors Include But Not Limited To:

• File content modification (code, comments, configuration, etc.)
• File renaming
• File moving
• File deletion
• New file creation
• Folder structure adjustment

Mandatory Execution Process:

Step Execution → Discover Issues → Execute Modifications → 🔥 Immediately Re-execute That Step → Verify No Omissions → User Confirmation → Next Step

Re-check Process After Problem Fix

When issues are discovered and modifications made in any step, must follow this process:

1. Execute Modification Operations

   • Make specific modifications based on discovered issues
   • Ensure modification content is accurate
   • Update file header modification records, version numbers and @lastModified fields

2. 🔥 Immediately Re-execute Current Step

   • Cannot skip this step!
   • Complete re-execution of all check items for that step
   • Cannot only check modified parts, must comprehensively re-check

3. Provide Verification Report

   • Confirm previously discovered issues are resolved
   • Confirm no new issues introduced
   • Confirm no other issues omitted

4. Wait for User Confirmation

   • Provide complete verification report
   • Wait for user confirmation before proceeding to next step

Verification Report Template

## Step X: Modification Verification Report

### 🔧 Executed Modification Operations
- Modification Type: [File modification/renaming/moving/deletion, etc.]
- Modification Content: [Specific modification description]
- Affected Files: [List of affected files]

### 📝 Updated Modification Records
- Added Modification Record: [User Date]: [Modification Type] - [Modification Content] (Modified by: [User Name])
- Updated Version Number: [Old Version] → [New Version]
- Updated Timestamp: @lastModified [User Date]

### 🔍 Re-executed Step X Complete Check Results
[Complete re-execution results of all check items for that step]

### ✅ Verification Status
- Original Issues Resolved ✓
- Modification Records Updated ✓
- No New Issues Introduced ✓
- No Other Issues Omitted ✓
- Step X Check Completely Passed ✓

**🔥 Important: This step has completed modification and re-verification, please confirm before proceeding to next step**

Importance of Re-checking

• Ensure Completeness: Avoid omitting other issues during modification process
• Prevent New Issues: Ensure modifications do not introduce new problems
• Maintain Quality: Each step reaches complete inspection standards
• Maintain Consistency: Ensure rigor throughout entire inspection process
• 🔥 Mandatory Execution: Cannot skip this step after modifications

⚡ Key Success Factors

• Strict Step-by-step Execution: No step skipping, no merged execution
• 🔥 Immediately Re-execute After Modification: Must immediately re-execute current step after any modification behavior, cannot directly proceed to next step
• Must Re-check After Problem Fix: Must re-execute entire step after file modification to ensure no omissions
• Must Update Modification Records: Must update file header modification records, version numbers and timestamps after each file modification
• Real Modification Verification: Verify modification effects through tools
• Accurate User Info Usage: Correctly apply date and name information
• Project Characteristic Adaptation: Optimize inspections for game server characteristics
• Complete Report Provision: Provide detailed inspection reports for each step

---

Before starting execution, please first run node tools/setup-user-info.js to set user information!