Add `.claude/` Claude Code tooling and root `CLAUDE.md` by yungyuc · Pull Request #770 · solvcon/modmesh

yungyuc · 2026-05-12T12:53:04Z

Set up project-tuned Claude Code configuration so the agent loads the project-specific guidance and uses the right wrappers, subagents, and deterministic checks when working on this codebase.

Root CLAUDE.md (replacing the gitignored placeholder): project overview, Claude Code Tooling index (slash commands, subagents, hooks, settings, status line), Build Commands quick reference and configuration, Architecture summary with load-bearing pieces and a pointer to cpp/modmesh/, Code Style at-a-glance (full rules in STYLE.md), PR guidelines, development notes, and common development patterns.

Remove the now-redundant contrib/prompt/CLAUDE.md and update gitignore entry for the root CLAUDE.local.md.

.claude/:

settings.json: permission allow/deny scoped to the Makefile workflow (make targets, cmake, pytest, lint/format tools, read-only git/gh). Destructive operations (force push, hard reset, git clean -fd, rm -rf / and ~, sudo) blocked; make clean/cmakeclean deliberately prompt. Wires the hook and the status line below.
hooks/check-source.sh: PostToolUse on Write|Edit of source files (*.py, *.cpp, *.hpp, ...). Deterministic checks for non-ASCII bytes, trailing whitespace, missing modeline, and Python >79 chars; exits 2 with path:line -- rule -- fix.
statusline.sh: reads session JSON via jq; prints <model> | <project> | <branch>[*if dirty] | ctx <%>.
commands/{build,pytest,gtest,lint,format}.md: slash commands wrapping the corresponding make targets. Each ends with verdict: clean | issues found | blocking.
agents/{cpp,python}-style-reviewer.md -- judgment-call style reviewers (m_ prefix in context, function-body placement, SimpleCollector preference, pybind11 binding split, test intent, naming). Scoped to git diff; pinned model: sonnet. Defer to STYLE.md as canonical; hooks own the deterministic rules.

Aslo add a standalone reference file contrib/prompt/general-rule.md without automaticaly imported into CLAUDE.md.

Set up project-tuned Claude Code configuration so the agent loads the project-specific guidance and uses the right wrappers, subagents, and deterministic checks when working on this codebase. Root `CLAUDE.md` (replacing the gitignored placeholder): project overview, Claude Code Tooling index (slash commands, subagents, hooks, settings, status line), Build Commands quick reference and configuration, Architecture summary with load-bearing pieces and a pointer to `cpp/modmesh/`, Code Style at-a-glance (full rules in `STYLE.md`), PR guidelines, development notes, and common development patterns. Remove the now-redundant `contrib/prompt/CLAUDE.md` and update gitignore entry for the root `CLAUDE.local.md`. `.claude/`: - `settings.json`: permission allow/deny scoped to the Makefile workflow (`make` targets, `cmake`, `pytest`, lint/format tools, read-only `git`/`gh`). Destructive operations (force push, hard reset, `git clean -fd`, `rm -rf /` and `~`, `sudo`) blocked; `make clean`/`cmakeclean` deliberately prompt. Wires the hook and the status line below. - `hooks/check-source.sh`: PostToolUse on `Write|Edit` of source files (`*.py`, `*.cpp`, `*.hpp`, ...). Deterministic checks for non-ASCII bytes, trailing whitespace, missing modeline, and Python `>79` chars; exits 2 with `path:line -- rule -- fix`. - `statusline.sh`: reads session JSON via `jq`; prints `<model> | <project> | <branch>[*if dirty] | ctx <%>`. - `commands/{build,pytest,gtest,lint,format}.md`: slash commands wrapping the corresponding `make` targets. Each ends with `verdict: clean | issues found | blocking`. - `agents/{cpp,python}-style-reviewer.md` -- judgment-call style reviewers (`m_` prefix in context, function-body placement, `SimpleCollector` preference, pybind11 binding split, test intent, naming). Scoped to `git diff`; pinned `model: sonnet`. Defer to `STYLE.md` as canonical; hooks own the deterministic rules. Aslo add a standalone reference file `contrib/prompt/general-rule.md` without automaticaly imported into `CLAUDE.md`.

yungyuc · 2026-05-12T12:54:00Z

@@ -1,4 +1,4 @@
-/CLAUDE.md
+CLAUDE.local.md


Ignore local claude context file.

Per https://www.reddit.com/r/ClaudeAI/comments/1nuunhu/is_claudelocalmd_deprecated/, CLAUDE.local.md is deprecated so it's no need to put this line.

It's not deprecated: https://code.claude.com/docs/en/memory#choose-where-to-put-claude-md-files

CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded in full at launch. Files in subdirectories load on demand when Claude reads files in those directories. See How CLAUDE.md files load for the full resolution order.

yungyuc · 2026-05-12T12:56:44Z

+- Qt-based GUI (pilot) for spatial data visualization
+- Integrated runtime profiler for performance analysis
+
+## Claude Code Tooling


Explain the tooling contents in the new .claude/ directory.

yungyuc · 2026-05-12T12:57:08Z

+in `contrib/prompt/general-rule.md` (not auto-imported). This section indexes
+the tools.
+
+### Slash commands (`.claude/commands/`)


Add commands for concrete operations.

yungyuc · 2026-05-12T12:57:28Z

+
+All commands end with `verdict: clean | issues found | blocking`.
+
+### Subagents (`.claude/agents/`)


Start with reviewing subagents. We can and will add more later.

yungyuc · 2026-05-12T12:58:27Z

+
+## Code Style
+
+`STYLE.md` is the canonical source. At a glance:


Point to the canonical style guide.

yungyuc · 2026-05-12T12:59:06Z

+
+### Running Single Tests
+
+Prefer the slash commands (`/pytest <path or args>`,


Describe testing operations in the slash commands. Here only list basic examples.

yungyuc · 2026-05-12T13:01:00Z

+
+modmesh uses a dual-layer hybrid architecture:
+
+1. **C++ Core** (`cpp/modmesh/`): High-performance numerical code


Remove the static list and point to the directory structure.

yungyuc · 2026-05-12T13:02:21Z

+
+### C++ Component Structure
+
+C++ core lives in `cpp/modmesh/`. Load-bearing pieces:


Claude rephrased this and it looks clearer to me.

yungyuc · 2026-05-12T13:03:39Z

The file is shorten from 363 lines to 276 lines.

yungyuc · 2026-05-12T21:58:35Z

Merged. @chestercheng @tigercosmos feel free to comment. Points you raise will be addressed in future PRs.

tigercosmos

@yungyuc Reviewed.

tigercosmos · 2026-05-12T23:46:02Z

+name: cpp-style-reviewer
+description: Judgment-call C++ review for modmesh (m_ prefix, function-body placement, SimpleCollector preference, pybind11 binding split, const_cast). Use proactively after editing files in cpp/.
+tools: Read, Grep, Glob, Bash
+model: sonnet


I prefer to use opus directly. Maybe it's better to put inherit here.

Sounds good to me.

Tracked in issue #774.

tigercosmos · 2026-05-12T23:50:24Z

@@ -0,0 +1,77 @@
+---


This file sounds more like a skill. A reviewer agent will call the C++ style skill and the python style skill.

I am OK to make it a skill. I am not familiar with either (sub-)agent nor skill and do not mind to change between them back and forth to experiment.

Tracked in issue #774.

tigercosmos · 2026-05-12T23:52:48Z

+  logs.
+
+End with: `verdict: clean | issues found | blocking`. `blocking`
+iff the build failed.


If and only if.

tigercosmos · 2026-05-12T23:56:25Z

@@ -0,0 +1,18 @@
+---


These commands have no more information than Makefile. I think we can just use a skill describe how to use the make file.

Sounds good to me.

tigercosmos · 2026-05-12T23:57:55Z

+in `contrib/prompt/general-rule.md` (not auto-imported). This section indexes
+the tools.
+
+### Slash commands (`.claude/commands/`)


As CLAUDE.md describes how to use make commands. All files in .claudes/commands seems redundant.

Right, and putting all the make uses in CLAUDE.md may be more concise for both human and machine minds. We can change it back.

Tracking in issue #773

tigercosmos · 2026-05-12T23:59:20Z

@@ -1,4 +1,4 @@
-/CLAUDE.md
+CLAUDE.local.md


Per https://www.reddit.com/r/ClaudeAI/comments/1nuunhu/is_claudelocalmd_deprecated/, CLAUDE.local.md is deprecated so it's no need to put this line.

yungyuc self-assigned this May 12, 2026

yungyuc added the documentation Improvements or additions to documentation label May 12, 2026

yungyuc commented May 12, 2026

View reviewed changes

yungyuc marked this pull request as ready for review May 12, 2026 13:03

yungyuc requested review from chestercheng and tigercosmos May 12, 2026 13:04

yungyuc merged commit 0ce99ed into solvcon:master May 12, 2026
14 checks passed

yungyuc deleted the dev/claude-dir branch May 12, 2026 21:57

tigercosmos reviewed May 12, 2026

View reviewed changes

This was referenced May 13, 2026

Clearly and concisely describe how to run tests in CLAUDE.md instead of using slash commands #773

Closed

Make reviewer agents as skills #774

Closed


		All commands end with `verdict: clean \| issues found \| blocking`.

		### Subagents (`.claude/agents/`)


		## Code Style

		`STYLE.md` is the canonical source. At a glance:


		### Running Single Tests

		Prefer the slash commands (`/pytest <path or args>`,


		modmesh uses a dual-layer hybrid architecture:

		1. C++ Core (`cpp/modmesh/`): High-performance numerical code


		### C++ Component Structure

		C++ core lives in `cpp/modmesh/`. Load-bearing pieces:

Conversation

yungyuc commented May 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

yungyuc commented May 12, 2026

Uh oh!

tigercosmos left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants