whale-town-end/docs/ai-reading/README.md

AI Code Inspection Guide - Whale Town Game Server

⚠️ 🚨 CRITICAL: MANDATORY PRE-EXECUTION REQUIREMENTS 🚨 ⚠️

<EFBFBD> AI MUST READ THIS SECTION FIRST - EXECUTION WITHOUT COMPLETING THESE STEPS IS STRICTLY FORBIDDEN 🔴

⛔ STOP! Before executing ANY step (including Step 1), you MUST complete ALL items in this section! ⛔

---

🎯 Pre-execution Setup (MANDATORY - CANNOT BE SKIPPED)

🚀 User Information Setup (STEP 0 - MUST EXECUTE FIRST)

⚠️ CRITICAL: Before starting any inspection steps (including Step 1), MUST run the user information script:

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

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

🚨 VERIFICATION CHECKPOINT:

• Have you executed node tools/setup-user-info.js?
• Does docs/ai-reading/me.config.json file exist?
• Have you read and confirmed the user's date and name from the config file?

⛔ IF ANY CHECKBOX ABOVE IS UNCHECKED, YOU CANNOT PROCEED TO STEP 1! ⛔

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 (MUST UNDERSTAND BEFORE STEP 1)

⚠️ AI MUST read and understand these characteristics BEFORE executing Step 1:

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)

🚨 VERIFICATION CHECKPOINT:

• Have you read and understood the project is a NestJS Game Server?
• Have you understood the dual-mode architecture?
• Have you understood the WebSocket real-time communication feature?
• Have you understood the property testing requirements?
• Have you understood the layered architecture?

⛔ IF ANY CHECKBOX ABOVE IS UNCHECKED, YOU CANNOT PROCEED TO STEP 1! ⛔

---

🚨 FINAL PRE-EXECUTION CHECKLIST (MUST COMPLETE BEFORE STEP 1) 🚨

Before proceeding to Step 1, AI MUST confirm ALL of the following:

✅ Mandatory Completion Checklist:

• ✅ Executed node tools/setup-user-info.js script
• ✅ Confirmed me.config.json file exists and contains valid date and name
• ✅ Read and stored user's date from config file
• ✅ Read and stored user's name from config file
• ✅ Understood this is a NestJS Game Server project
• ✅ Understood the dual-mode architecture (database + memory)
• ✅ Understood the WebSocket real-time communication feature
• ✅ Understood the property testing requirements
• ✅ Understood the layered architecture (Core + Business)
• ✅ Read and understood the execution principles below

🔴 CRITICAL RULE:

IF ANY ITEM IN THE CHECKLIST ABOVE IS NOT COMPLETED, AI IS ABSOLUTELY FORBIDDEN FROM EXECUTING STEP 1 OR ANY OTHER STEPS!

AI MUST explicitly confirm completion of ALL checklist items before proceeding to Step 1!

---

🔄 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
    ↓
🚨 MANDATORY: Execute node tools/setup-user-info.js
    ↓
🚨 MANDATORY: Verify me.config.json exists
    ↓
🚨 MANDATORY: Read and Store User Info (date, name)
    ↓
🚨 MANDATORY: Understand Project Characteristics
    ↓
🚨 MANDATORY: Complete Pre-execution Checklist
    ↓
🚨 MANDATORY: Explicitly Confirm ALL Checklist Items Completed
    ↓
⛔ CHECKPOINT: Cannot proceed without completing above steps ⛔
    ↓
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

🚨 REMINDER: Before executing Step 1, ensure you have completed ALL items in the "FINAL PRE-EXECUTION CHECKLIST" above! 🚨

Step 1: Naming Convention Check

⚠️ BEFORE STARTING STEP 1, AI MUST:

1. ✅ Confirm node tools/setup-user-info.js has been executed
2. ✅ Confirm user date and name have been read from me.config.json
3. ✅ Confirm project characteristics have been understood
4. ✅ Explicitly state: "Pre-execution checklist completed, now starting Step 1"

ONLY AFTER EXPLICIT CONFIRMATION CAN STEP 1 BEGIN!

---

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 detection, branch management, commit message standards, merge document generation 🚨 Important Principle: Regardless of when or what type of changes were made, if Git detects changes, provide commit service After completion: Provide commit report, generate merge document

📋 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

---

🔴 FINAL WARNING 🔴

⚠️ AI EXECUTION REQUIREMENTS SUMMARY:

1. STEP 0 (MANDATORY): Execute node tools/setup-user-info.js
2. STEP 0.1 (MANDATORY): Verify me.config.json exists and read user info
3. STEP 0.2 (MANDATORY): Understand project characteristics
4. STEP 0.3 (MANDATORY): Complete and explicitly confirm pre-execution checklist
5. ONLY THEN: Begin Step 1

🚨 VIOLATION CONSEQUENCES:

• If AI skips Step 0 and directly executes Step 1, user MUST stop AI and require restart
• If AI does not explicitly confirm checklist completion, user MUST stop AI and require confirmation
• If AI does not read user info from config file, all subsequent steps are INVALID

✅ CORRECT EXECUTION START:

AI: "I will now begin the code inspection process.

Step 0 - Pre-execution Setup:
1. ✅ Executing user information setup script...
   Command: cd docs/ai-reading && node tools/setup-user-info.js
   
2. ✅ Verifying me.config.json exists...
   File found: docs/ai-reading/me.config.json
   
3. ✅ Reading user information...
   User Date: 2026-01-19
   User Name: [Name from config]
   
4. ✅ Understanding project characteristics...
   - NestJS Game Server ✓
   - Dual-mode Architecture ✓
   - WebSocket Communication ✓
   - Property Testing ✓
   - Layered Architecture ✓
   
5. ✅ Pre-execution checklist completed!

All mandatory pre-execution requirements have been satisfied.
Now proceeding to Step 1: Naming Convention Check..."

⛔ INCORRECT EXECUTION START (FORBIDDEN):

AI: "I will start with Step 1: Naming Convention Check..." ❌ WRONG!
AI: "Let me check the naming conventions..." ❌ WRONG!
AI: "Starting code inspection..." ❌ WRONG!

---

🎯 Remember: Step 0 is NOT optional - it is MANDATORY before ANY other step!