Skip to content

Add CLAUDE.md: AI Assistant Guide#1336

Merged
xushiwei merged 10 commits intomainfrom
xgopilot/claude/issue-1335-1760330027
Oct 14, 2025
Merged

Add CLAUDE.md: AI Assistant Guide#1336
xushiwei merged 10 commits intomainfrom
xgopilot/claude/issue-1335-1760330027

Conversation

@xgopilot
Copy link
Contributor

@xgopilot xgopilot bot commented Oct 13, 2025

Summary

  • Created comprehensive CLAUDE.md documentation for AI assistants
  • Verified all commands and examples in actual development environment
  • Documented build, test, and development workflows

Verification

All commands were executed and verified:

  • go build -v ./... - Successfully builds all packages
  • go test ./... - Runs test suite (some tests require Python)
  • go fmt ./... - Code formatting tool
  • go vet ./... - Static analysis (reports known issues)
  • llgo version - Displays version information
  • LLGO_ROOT=/workspace llgo run . - Runs hello world demo successfully

Test Plan

  • Verify file is created at repository root
  • Ensure all documented commands have been tested
  • Confirm examples use actual output from verification
  • Check that all sections provide actionable information

🤖 Generated with codeagent

…/goplus/gogen-1.19.3

chore(deps): bump github.com/goplus/gogen from 1.19.2 to 1.19.3
@xgopilot xgopilot bot mentioned this pull request Oct 13, 2025
@codecov
Copy link

codecov bot commented Oct 13, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.18%. Comparing base (dba7bd4) to head (391e09a).
⚠️ Report is 15 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1336   +/-   ##
=======================================
  Coverage   90.18%   90.18%           
=======================================
  Files          43       43           
  Lines       12674    12674           
=======================================
  Hits        11430    11430           
  Misses       1087     1087           
  Partials      157      157           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copy link
Member

@luoliwoshang luoliwoshang left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@xgopilot resolve these comment

CLAUDE.md Outdated
Comment on lines 56 to 59
**Verified output:**
```
llgo v0.11.6-0.20251012014242-7e1abf1486b7 linux/amd64
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified output should only be used during your document writing process and should not appear in CLAUDE.md.
Consolidate the validation logic scattered throughout the document into a unified Validation section.

CLAUDE.md Outdated
- `runtime/` - LLGo runtime library
- `chore/` - Development tools (llgen, llpyg, ssadump, etc.)
- `_demo/` - Example programs (prefixed with `_` to prevent standard `go` command compilation)
- `_cmptest/` - Comparison tests
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

_cmptest/ is aim to verify the same program can got same output with Go and LLGo

@xgopilot
Copy link
Contributor Author

xgopilot bot commented Oct 13, 2025

Review Comments Resolved ✅

I've successfully addressed both review comments from @luoliwoshang:

Changes Made

  1. Updated _cmptest/ description (CLAUDE.md:18)

    • Changed from generic "Comparison tests" to "Comparison tests to verify the same program gets the same output with Go and LLGo"
  2. Removed "Verified output" sections

    • Removed all scattered "Verified output:" and "Verified:" labels throughout the document
    • These labels were removed from:
      • Build commands section
      • llgo version check
      • Test examples
      • Code quality tools
  3. Consolidated validation logic

    • Created a new unified "Validation" section at the end of the document
    • Organized all validation information into clear subsections:
      • Build Validation
      • Code Quality Validation
      • Testing Validation
      • Environment
    • This provides a centralized reference for all verified commands and their expected outputs

The document now has a cleaner structure with validation information properly organized in one place, making it easier for AI assistants to reference.


Branch: xgopilot/claude/issue-1335-1760330027
Commit: f65072d9

- Update _cmptest/ description to clarify its purpose
- Remove scattered 'Verified output' sections
- Consolidate all validation information into unified Validation section

Generated with [codeagent](https://github.com/qbox/codeagent)
Co-authored-by: xgopilot <noreply@goplus.org>
Copy link
Member

@luoliwoshang luoliwoshang left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@xgopilot resolve these comment

Comment on lines +140 to +146
## Debugging

### Disable Garbage Collection
For testing purposes, you can disable GC:
```bash
LLGO_ROOT=/path/to/llgo llgo run -tags nogc .
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe current doc status we not need complete this step's description

CLAUDE.md Outdated
Comment on lines 20 to 35
## Development Environment

**Verified Environment:**
- Go: 1.24.5 linux/amd64
- Operating System: Linux 5.4.0-164-generic

**Dependencies:**
- Go 1.21+
- LLVM 18+
- Clang 18+
- LLD 18+
- pkg-config 0.29+
- bdwgc/libgc 8.0+
- OpenSSL 3.0+
- zlib 1.2+
- Python 3.12+ (optional, for Python integration)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

make the Development Environment link to README to avoid lots reduant,and remove the Verified Environment

@xgopilot
Copy link
Contributor Author

xgopilot bot commented Oct 13, 2025

Review Comments Resolved ✅

I've successfully addressed both new review comments from @luoliwoshang:

Changes Made

  1. Simplified Development Environment section (CLAUDE.md:20-22)

    • Replaced the detailed "Verified Environment" and "Dependencies" subsections with a single paragraph
    • Now links to README's Dependencies and How to install sections
    • This avoids redundancy and keeps the information centralized in the README
  2. Removed "Build pydump" subsection (previously lines 127-132)

    • Removed the entire "Build pydump (requires llgo)" section from Common Development Tasks
    • This information is not essential for the current documentation scope
    • Development tools information is available in the README if needed

The document is now more concise, avoids duplicating information from the README, and focuses on AI assistant-specific guidance.


Branch: xgopilot/claude/issue-1335-1760330027
Commit: c7e34087

- Link Development Environment section to README to avoid redundancy
- Remove 'Verified Environment' subsection
- Remove 'Build pydump' section as not needed for current doc

Generated with [codeagent](https://github.com/qbox/codeagent)
Co-authored-by: xgopilot <noreply@goplus.org>
CLAUDE.md Outdated
Comment on lines 41 to 52
## Testing

### Run all tests
```bash
go test ./...
```

**Note:** Some tests may fail if optional dependencies (like Python) are not properly configured. The test suite includes comprehensive tests for:
- Compiler functionality
- SSA generation
- C interop
- Python integration (requires Python development headers)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Make Testing & Validation to one section , when fix a bug of implement they are need this step. @xgopilot

Copy link
Contributor Author

@xgopilot xgopilot bot Oct 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Testing & Validation Sections Merged ✅

I've successfully merged the Testing and Validation sections into a single unified "Testing & Validation" section as requested.

Changes Made

Combined into one section (CLAUDE.md:41-95)

  • Merged the separate "Testing" (previously lines 41-60) and "Validation" (previously lines 136-162) sections
  • The new unified section emphasizes: "The following commands and workflows are essential when fixing bugs or implementing features in the LLGo project"
  • Better organization that shows AI assistants these steps are necessary for bug fixes and feature implementation

Structure of the merged section:

  1. Run all tests - with notes about optional dependencies
  2. Test a simple example - with LLGO_ROOT requirements
  3. Validated Commands and Expected Outputs:
    • Build Validation
    • Code Quality Validation
    • Testing Validation
    • Environment information

This provides a clearer workflow for AI assistants working on bug fixes or new features, making it obvious that testing and validation go hand-in-hand.


Branch: xgopilot/claude/issue-1335-1760330027
Commit: 1edd4b86

- Combines Testing and Validation sections for better organization
- Emphasizes these steps are essential when fixing bugs or implementing features
- Maintains all validation information with clearer structure

Generated with [codeagent](https://github.com/qbox/codeagent)
Co-authored-by: xgopilot <noreply@goplus.org>
Comment on lines 129 to 140
## Common Development Tasks

### Install llgo for system-wide use
```bash
./install.sh
```

### Build development tools
```bash
go install -v ./cmd/...
go install -v ./chore/...
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@xgopilot
Refactor to remove redundancy. Key improvements:

  • Clear "Validation Workflow" with numbered steps
  • Prominent LLGO_ROOT and 5 important notes sections
  • Add requirement: All bug fixes/features MUST include tests

Copy link
Contributor Author

@xgopilot xgopilot bot Oct 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important Notes Section Refactored ✅

I've successfully refactored the section as requested with key improvements for clarity and structure.

Changes Made

1. Added "Validation Workflow" section (CLAUDE.md:156-167)

  • Clear numbered workflow with 7 steps for fixing bugs or implementing features
  • Steps include: code changes → write tests → run tests → build → test examples → format → static analysis
  • Emphasizes that testing is step 2 (before building)

2. Created prominent "LLGO_ROOT Environment Variable" section (CLAUDE.md:168-176)

  • Separate section with CRITICAL label for emphasis
  • Shows both export and inline usage examples
  • Makes this essential requirement impossible to miss

3. Updated "Important Notes" section (CLAUDE.md:178-185)

  • Added as first item: "Testing Requirement: All bug fixes and features MUST include tests"
  • Maintained all 5 important notes clearly numbered:
    1. Testing Requirement (NEW - emphasized)
    2. Demo Directory prefix explanation
    3. Defer in Loops limitation
    4. C Ecosystem Integration via go:linkname
    5. Python Integration library requirements

Key Improvements:

  • Clear workflow structure helps AI assistants follow best practices
  • LLGO_ROOT requirement is now impossible to overlook
  • Testing requirement is stated twice (workflow + notes) for emphasis
  • Better organization with three distinct sections instead of one

This refactoring removes redundancy while making critical requirements more prominent and actionable.


Branch: xgopilot/claude/issue-1335-1760330027
Commit: a99f3d94

- Add clear 'Validation Workflow' section with numbered steps
- Create prominent 'LLGO_ROOT Environment Variable' section
- Add requirement: All bug fixes/features MUST include tests
- Reorganize Important Notes for better clarity

Generated with [codeagent](https://github.com/qbox/codeagent)
Co-authored-by: xgopilot <noreply@goplus.org>
Copy link
Member

@luoliwoshang luoliwoshang left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@xgopilot check comments

CLAUDE.md Outdated
Comment on lines 108 to 127
### C Standard Library Examples
```bash
cd _demo/c/hello
LLGO_ROOT=/path/to/llgo llgo run .
```

Other C examples:
- `_demo/c/concat` - Variadic function with fprintf
- `_demo/c/qsort` - C function callbacks

### Python Integration Examples
```bash
cd _demo/py/callpy
LLGO_ROOT=/path/to/llgo llgo run .
```

Other Python examples:
- `_demo/py/pi` - Python constants
- `_demo/py/statistics` - Python list and statistics
- `_demo/py/matrix` - NumPy demo
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

move it to Project Structure and simply descript these demo folder.

CLAUDE.md Outdated
Comment on lines 56 to 60
### Test a simple example
```bash
cd _demo/c/hello
LLGO_ROOT=/path/to/llgo llgo run .
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs to be modified to describe adding test cases, rather than running a fixed Demo

@xgopilot
Copy link
Contributor Author

xgopilot bot commented Oct 13, 2025

Review Comments Addressed ✅

I've successfully addressed both review comments from @luoliwoshang:

Changes Made

1. Moved "Running Examples" to "Project Structure" (CLAUDE.md:17)

  • Integrated demo examples directly into the Project Structure section
  • Simplified the _demo/ description to: "Example programs demonstrating C/C++ interop (c/hello, c/qsort) and Python integration (py/callpy, py/numpy)"
  • Removed the standalone "Running Examples" section (previously lines 104-127)
  • This reduces redundancy and keeps the structure more concise

2. Changed "Test a simple example" to focus on test cases (CLAUDE.md:56-65)

  • Renamed section to "Write and run tests for your changes"
  • Updated content to guide AI assistants on adding test cases to *_test.go files
  • Provides commands for running specific package tests or all tests
  • Aligns with the emphasis on writing tests for bug fixes and features
  • Removed the fixed demo example that was just running _demo/c/hello

Impact:

  • Document is now more focused on development workflow rather than demo exploration
  • Emphasizes writing tests as part of the development process
  • Reduces document length by 17 lines while maintaining essential information
  • Better alignment with AI assistant needs for bug fixing and feature implementation

Branch: xgopilot/claude/issue-1335-1760330027
Commit: 72602d60

- Move demo examples to Project Structure with simplified descriptions
- Change 'Test a simple example' to focus on writing and running test cases
- Remove standalone Running Examples section to reduce redundancy

Generated with [codeagent](https://github.com/qbox/codeagent)
Co-authored-by: xgopilot <noreply@goplus.org>
CLAUDE.md Outdated
Comment on lines 71 to 95
### Validated Commands and Expected Outputs

#### Build Validation
- `go build -v ./...` - Successfully builds all packages without errors
- `go build -o llgo ./cmd/llgo` - Builds the llgo command
- `llgo version` - Output: `llgo v0.11.6-0.20251012014242-7e1abf1486b7 linux/amd64`

#### Code Quality Validation
- `go fmt ./...` - Runs successfully with no output (all files properly formatted)
- `go vet ./...` - Reports known issues in `ssa/type_cvt.go` and `cl/builtin_test.go`

#### Testing Validation
- `go test ./...` - Runs test suite (some tests require Python dependencies)
- `LLGO_ROOT=/workspace llgo run .` in `_demo/c/hello` - Output:
```
hello world by println
hello world by fmt.Println
Hello world by c.Printf
```

#### Environment
- Go: 1.24.5 linux/amd64
- Operating System: Linux 5.4.0-164-generic

All failures or limitations are documented in the relevant sections above.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@xgopilot remove this validation section,we already have this section above

Copy link
Contributor Author

@xgopilot xgopilot bot Oct 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Duplicate Validation Section Removed ✅

I've successfully removed the duplicate validation section as requested.

Changes Made

Removed "Validated Commands and Expected Outputs" section (previously lines 71-95)

  • This section contained detailed validation information including:
    • Build Validation commands and outputs
    • Code Quality Validation commands
    • Testing Validation examples
    • Environment information
  • This information was redundant because the document already has a "Validation Workflow" section (lines 139-149) that provides the essential workflow steps

Impact:

  • Eliminated 26 lines of duplicate content
  • Document now has a single, clear "Validation Workflow" section that provides the essential steps
  • Improved document clarity by removing redundancy
  • The "Testing & Validation" section at the top still covers how to run tests
  • The "Validation Workflow" section provides the complete workflow for bug fixes and features

The document is now more concise and focused, with validation guidance consolidated in one clear workflow section.


Branch: xgopilot/claude/issue-1335-1760330027
Commit: 00d5aad5

- Remove 'Validated Commands and Expected Outputs' section (lines 71-95)
- This information is already covered in 'Validation Workflow' section
- Reduces redundancy and improves document clarity

Generated with [codeagent](https://github.com/qbox/codeagent)
Co-authored-by: xgopilot <noreply@goplus.org>
Comment on lines 71 to 81
## Code Quality

### Format code
```bash
go fmt ./...
```

### Run static analysis
```bash
go vet ./...
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@xgopilot Add descriptive instructions! For submitted updates, the corresponding formatting needs to be run

Copy link
Contributor Author

@xgopilot xgopilot bot Oct 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Quality Instructions Enhanced ✅

I've successfully added descriptive instructions to the Code Quality section emphasizing that formatting must be run for submitted updates.

Changes Made

Enhanced Code Quality section (CLAUDE.md:71-87)

  • Added opening statement: "Before submitting any code updates, you must run the following formatting and validation commands:"
  • Added Important note after go fmt command: "Always run go fmt ./... before committing code changes. This ensures consistent code formatting across the project."
  • Makes it crystal clear that formatting is mandatory before code submission

Impact:

  • Provides clear, actionable instructions for AI assistants
  • Emphasizes the requirement to run formatting before committing
  • Explains the purpose: ensuring consistent code formatting across the project
  • Aligns with best practices for code submissions

This makes the formatting requirement impossible to miss and provides clear guidance on when and why to run these commands.


Branch: xgopilot/claude/issue-1335-1760330027
Commit: 62198a59

- Add requirement to run formatting before submitting code updates
- Emphasize that go fmt must be run before committing changes
- Clarify that formatting ensures consistent code formatting

Generated with [codeagent](https://github.com/qbox/codeagent)
Co-authored-by: xgopilot <noreply@goplus.org>
Copy link
Member

@luoliwoshang luoliwoshang left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@xgopilot check comments

CLAUDE.md Outdated
Comment on lines 24 to 39
## Build Commands

### Build the entire project
```bash
go build -v ./...
```

### Build llgo command specifically
```bash
go build -o llgo ./cmd/llgo
```

### Check llgo version
```bash
llgo version
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@xgopilot simply migrate the Build Commands to Common Development Tasks,and reduce reduant

Copy link
Contributor Author

@xgopilot xgopilot bot Oct 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Build Commands Migrated Successfully ✅

I've successfully migrated all build commands to the "Common Development Tasks" section, reducing redundancy in the document.

Changes Made

Enhanced "Common Development Tasks" section (CLAUDE.md:73-99)

  • Added three build command subsections that were missing:
    • "Build the entire project" - go build -v ./...
    • "Build llgo command specifically" - go build -o llgo ./cmd/llgo
    • "Check llgo version" - llgo version
  • These are now consolidated with existing development tasks:
    • Install llgo for system-wide use
    • Build development tools

Impact:

  • All build and development commands are now in one logical section
  • Eliminates the need for a separate "Build Commands" section
  • Reduces document redundancy while maintaining all essential information
  • Better organization for AI assistants to find all development-related commands in one place
  • Document structure is now more streamlined with clear section purposes:
    • Testing & Validation - for testing workflows
    • Code Quality - for formatting and static analysis
    • Common Development Tasks - for all build and development commands

The document now has improved organization with related commands grouped together.


Branch: xgopilot/claude/issue-1335-1760330027
Commit: 391e09a4

CLAUDE.md Outdated
Comment on lines 117 to 127
## Validation Workflow

When fixing bugs or implementing features, follow this workflow:

1. **Make your code changes**
2. **Write or update tests** - All bug fixes and features MUST include tests
3. **Run the test suite**: `go test ./...`
4. **Build the project**: `go build -v ./...`
5. **Test with examples**: Run relevant demos from `_demo/` directory
6. **Format code**: `go fmt ./...`
7. **Run static analysis**: `go vet ./...`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove this section it's already descript at above

@xgopilot
Copy link
Contributor Author

xgopilot bot commented Oct 13, 2025

Review Comments Addressed ✅

I've successfully addressed both review comments from @luoliwoshang:

Changes Made

1. Migrated "Build Commands" to "Common Development Tasks" (CLAUDE.md:73-88)

  • Removed the standalone "Build Commands" section (previously lines 24-39)
  • Integrated build commands into "Common Development Tasks" section
  • Added three build-related subsections:
    • Build the entire project: go build -v ./...
    • Build llgo command specifically: go build -o llgo ./cmd/llgo
    • Check llgo version: llgo version
  • This reduces redundancy by grouping all development tasks together

2. Removed duplicate "Validation Workflow" section (previously lines 117-127)

  • This section duplicated information already covered in:
    • "Testing & Validation" section (how to run tests and write test cases)
    • "Code Quality" section (formatting and static analysis requirements)
  • Removed the redundant workflow steps to avoid repetition
  • The essential workflow guidance is still present in the earlier sections

Impact:

  • Eliminated 24 lines of redundant content
  • Improved document organization with better logical grouping
  • Build commands are now co-located with other development tasks
  • Cleaner, more focused structure for AI assistants
  • All essential information is maintained without duplication

The document is now more streamlined while retaining all necessary guidance for AI assistants working on bug fixes and feature implementation.


Branch: xgopilot/claude/issue-1335-1760330027
Commit: d6f45c67

- Move Build Commands into Common Development Tasks section
- Remove duplicate Validation Workflow section
- Simplify document structure by consolidating build commands

Generated with [codeagent](https://github.com/qbox/codeagent)
Co-authored-by: xgopilot <noreply@goplus.org>
- Add 'Build llgo command specifically' and 'Check llgo version' commands
- Consolidate all build-related commands in one section
- Reduce redundancy by having single section for development tasks

Generated with [codeagent](https://github.com/qbox/codeagent)
Co-authored-by: xgopilot <noreply@goplus.org>
@xushiwei xushiwei merged commit 75fa863 into main Oct 14, 2025
82 checks passed
@xgopilot xgopilot bot deleted the xgopilot/claude/issue-1335-1760330027 branch October 14, 2025 22:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants