From 079d2c3cb3980acf0e36cffc8f2d5a64730d2281 Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Mon, 15 Sep 2025 11:34:19 +0800
Subject: [PATCH] feat(docs): update CLAUDE.md to enhance AI assistant
 guidelines and add session tracking details

---
 .gitignore |  2 ++
 CLAUDE.md  | 72 ++++++++++++++++++++++++++++++++++++++++--------------
 2 files changed, 55 insertions(+), 19 deletions(-)

diff --git a/.gitignore b/.gitignore
index 39b5630926..6e4d9d6876 100644
--- a/.gitignore
+++ b/.gitignore
@@ -68,3 +68,5 @@ playwright-report
 test-results
 
 YOUR_MEMORY_FILE_PATH
+
+.sessions/
diff --git a/CLAUDE.md b/CLAUDE.md
index a2f0bf163f..1aebe635e3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,13 @@
-# CLAUDE.md
+# AI Assistant Guide
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to AI coding assistants when working with code in this repository. Adherence to these guidelines is crucial for maintaining code quality and consistency.
+
+## Guiding Principles
+
+- **Clarity and Simplicity**: Write code that is easy to understand and maintain.
+- **Consistency**: Follow existing patterns and conventions in the codebase.
+- **Correctness**: Ensure code is correct, well-tested, and robust.
+- **Efficiency**: Write performant code and use resources judiciously.
 
 ## Development Commands
 
@@ -20,9 +27,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **Preload Scripts** (`src/preload/`): Secure IPC bridge
 
 ### Key Components
-- **AI Core** (`src/renderer/src/aiCore/`): Middleware pipeline for multiple AI providers
+- **AI Core** (`src/renderer/src/aiCore/`): Middleware pipeline for multiple AI providers.
 - **Services** (`src/main/services/`): MCPService, KnowledgeService, WindowService, etc.
-- **Build System**: Electron-Vite with experimental rolldown-vite, yarn workspaces
+- **Build System**: Electron-Vite with experimental rolldown-vite, yarn workspaces.
+- **State Management**: Redux Toolkit (`src/renderer/src/store/`) for predictable state.
+- **UI Components**: HeroUI (`@heroui/*`) for all new UI elements.
 
 ### Logging
 ```typescript
@@ -32,24 +41,49 @@ const logger = loggerService.withContext('moduleName')
 logger.info('message', CONTEXT)
 ```
 
-## Session Tracking
+## Session Tracking (Plan Mode)
 
-When working in plan mode, Claude Code MUST:
+When in **plan mode**, maintain a session log in `.sessions/YYYY-MM-DD-HH-MM-SS-<feature>.md`. This is critical for tracking progress and decisions:
 
-1. **Create Session File**: Create a markdown file in `.sessions/` folder with format:
-   `YYYY-MM-DD-HH-MM-SS-<feature-name>.md`
+```md
+# <feature> — SDLC Session (<YYYY-MM-DD HH:MM>)
 
-2. **Track Progress**: After each code patch or significant change, update the session file with:
-   - What was changed
-   - Files modified
-   - Decisions made
-   - Next steps
+## Design Brief
+- Problem & goals:
+- Non-goals/scope:
+- Constraints & risks:
+- Acceptance criteria:
 
-3. **Keep Updated**: The session file must remain current throughout the entire development session
+## Solution Design
+- Architecture/flow:
+- Key interfaces:
+- Data model:
+- Test strategy:
 
-## Must Follow Rules
+## Work Plan
+| ID  | Task | Owner | Depends | Est | Status |
+| --- | ---- | ----- | ------- | --- | ------ |
+| T1  |      |       |         |     | TODO   |
 
-1. **Search Code**: Use `ast-grep` for code pattern searches if available, otherwise use `rg` or `grep` for text-based searches
-2. **UI Components**: Use HeroUI for new components - antd and styled-components are PROHIBITED
-3. **Quality Gate**: Run `yarn build:check` before any commits
-4. **Session Documentation**: Maintain session tracking file when in plan mode
+## Patch Log
+### <HH:MM>
+- Summary:
+- Files:
+- Tests/Commands:
+- Next:
+
+## Validation
+- [ ] Criteria met
+- [ ] build:check passes
+- [ ] Tests green
+```
+
+
+## MUST Follow Rules
+
+1.  **Code Search**: Use `ast-grep` for semantic code pattern searches when available. Fallback to `rg` (ripgrep) or `grep` for text-based searches.
+2.  **UI Framework**: Exclusively use **HeroUI** for all new UI components. The use of `antd` or `styled-components` is strictly **PROHIBITED**.
+3.  **Quality Assurance**: **Always** run `yarn build:check` before finalizing your work or making any commits. This ensures code quality (linting, testing, and type checking).
+4.  **Session Documentation**: When working in plan mode, consistently maintain the session SDLC log file following the template structure outlined in the Session Tracking section.
+5.  **Centralized Logging**: Use the `loggerService` exclusively for all application logging (info, warn, error levels) with proper context. Do not use `console.log`.
+6.  **External Research**: Leverage `subagent` for gathering external information, including latest documentation, API references, news, or web-based research. This keeps the main conversation focused on the task at hand.