I'm not sure if using /init is the best way to initialize this file. We need to think about what things we always want to initialize the context with. Most of what's in this file now doesn't seem like the most important stuff.

FWIW I wrote the claude.md on the internal codebase and there I just thought about everything I'd tell to a new engineer on the team. A lot of text there is really about workerd and could be copied out here.

But I'm not necessarily sure if that was the right approach. It doesn't seem like the usual way to use claude.md. But intuitively it seems right to me -- initialize the context with general high-level knowledge that you always need.

Most of what's in this file now doesn't seem like the most important stuff.

Depends on what do you think the most important stuff is? Currently it is basically set of commands to run and code layout. I trimmed some extra bits.

FWIW I wrote the claude.md on the internal codebase and there I just thought about everything I'd tell to a new engineer on the team. A lot of text there is really about workerd and could be copied out here.

But I'm not necessarily sure if that was the right approach. It doesn't seem like the usual way to use claude.md. But intuitively it seems right to me -- initialize the context with general high-level knowledge that you always need.

Firstly I have no idea what I am doing: my first attempt to use the tool :) But my plan was to start building on this and add additional architecture information after. This was not supposed to be "the final" version of CLAUDE.md but just something to start working with.

@danlapid CI is not run because we're only changing a markdown file. CI jobs are ignored, and this is an existing bug. This can only be landed by a person who has access to the repo as an admin. (cc @jasnell)

The only thing I'm apparently allowed to do even with admin rights is enable auto merge. It's not giving me the option to override.

@danlapid CI is not run because we're only changing a markdown file. CI jobs are ignored, and this is an existing bug. This can only be landed by a person who has access to the repo as an admin. (cc @jasnell)

heh. let me touch some source :)

Claude finished @mikea's task in 1m 45s —— View job

PR Review: CLAUDE.md

Todo List:

• Read and analyze CLAUDE.md content
• Provide comprehensive review feedback
• Address review criteria (code quality, bugs, performance, security, test coverage)
• Consider existing reviewer feedback

Review Findings

Overall Assessment

This is a solid initial CLAUDE.md file that provides comprehensive project context. The structure is logical and covers essential development workflows. However, there are several areas that need attention based on reviewer feedback and accuracy concerns.

Content Quality & Best Practices

Strengths:

• Well-organized structure covering build system, architecture, and workflows
• Good coverage of multiple build systems (Bazel + Just commands)
• Comprehensive architecture overview with directory structure
• Includes important concepts like backward compatibility and risky changes

Areas for Improvement:

1. Just Commands Verification (CLAUDE.md:22-32)

   • @kentonv mentioned unfamiliarity with these commands
   • Recommend verifying all just commands actually exist in the project
   • Consider adding a note about checking justfile for available commands

2. TypeScript Definitions Location (CLAUDE.md:55)

   • @jasnell correctly noted inaccuracy: "TypeScript definitions are derived from C++ implementation"
   • The actual TypeScript definitions don't live in api/* (except overrides)
   • Should clarify this is about generation process, not file locations

3. Node.js Implementation Details (CLAUDE.md:53)

   • Should be clarified per @jasnell's suggestion:
   • "C++ portions of the Node.js compatibility layer are in api/node/, while the JavaScript and TypeScript implementations live in src/node/"

Missing Critical Information

1. Compatibility Flags & Autogates (@jasnell's suggestion)

   • Should expand on compatibility-date.capnp usage
   • Add guidance on when autogates may be needed
   • This could help Claude automatically suggest when breaking changes need feature flags

2. Code Style Specifics

   • Current mention of clang-format is too generic
   • @jasnell noted workerd has exceptions to KJ style guide
   • Should be more specific about actual style used to avoid incorrect recommendations

Potential Issues

1. Editor Over-Documentation

   • @danlapid and @anonrig noted concerns about Zed editor documentation
   • Consider removing editor-specific content as it's not relevant to Claude

2. Package Manager Accuracy

   • @anonrig suggested correction to pnpm usage description
   • Should verify current package management setup

3. Command Recommendations

   • @danlapid mentioned not wanting to over-suggest bazel clean --expunge
   • Consider being more conservative with potentially disruptive commands

Security & Performance

• ✅ No security concerns for documentation file
• ✅ Performance not applicable to documentation
• ✅ No sensitive information exposed

Test Coverage Assessment

The file adequately covers testing workflows:

• Multiple test types documented
• Clear commands provided
• Good coverage of Node.js compatibility and Web Platform Tests

Recommendations

1. Immediate Fixes Needed:

   • Correct TypeScript definitions description (line 55)
   • Update Node.js implementation locations (line 53)
   • Verify all just commands exist

2. Enhancements:

   • Add more detail on compatibility flags and when to use them
   • Expand autogate guidance for risky changes
   • Clarify code style exceptions from KJ guidelines

3. Consider Removing:

   • Editor-specific documentation
   • Commands that maintainers are unfamiliar with

Final Assessment

This is a good foundation that addresses the core need for Claude context, but needs accuracy fixes and some content refinement based on maintainer feedback. The approach of providing high-level project knowledge is sound, though some specific details need verification and correction.