dev: update claude files for easier development with claude tools#142
dev: update claude files for easier development with claude tools#142
Conversation
|
Does Claude have an option to do code reviews instead of Copilot? I've seen you use Copilot previously to review your PR. Is it possible to switch to Claude instead of Copilot? |
It can be done by creating a GitHub action for code review. |
| | Docker | any | For Ghidra headless decompilation | | ||
| | Z3 | ≥ 4.8 | SMT solver; can use vendored (`PE_USE_VENDORED_Z3=ON`) or system | | ||
|
|
||
| Vendored and auto-built: `gflags`, `glog`, `rellic`, optionally `z3` and [clangir](https://github.com/trail-of-forks/clangir). |
There was a problem hiding this comment.
This should mention the versions of the vendored dependencies in a table similar to above, and where each of these lives, and their purpose in the project.
There should also be a sentence telling Claude (or any human readers) how to add new vendored dependencies: put them in a specific location, update the table in this readme.
| brew install cmake ninja lit colima docker docker-buildx docker-credential-helper | ||
| Test and firmware binaries are built in Docker via `firmwares/build.sh`. | ||
|
|
||
| ### Linux |
There was a problem hiding this comment.
This is not properly escaped with a prior ``` and instead appears as a comment inside the macOS section
| Vendored and auto-built: `gflags`, `glog`, `rellic`, optionally `z3` and [clangir](https://github.com/trail-of-forks/clangir). | ||
|
|
||
| ### macOS | ||
| ```sh |
There was a problem hiding this comment.
Sentence explaining that this is for installing dependencies, and that it relies on colima to provide docker for macos.
I believe there is some colima-specific setup that is also needed, and we talk about it in one of the readmes. That should be either referenced via linking to the document or directly put in here.
|
|
||
| ## Building | ||
|
|
||
| ### Step 0: Build the LLVM/ClangIR Fork (one-time) |
There was a problem hiding this comment.
If possible mention how long this would take.
Ideally we have a script that does this so no user ever has to invoke this manually (maybe we already do?)
| cmake --install builds/default --prefix ./builds/run --config Release | ||
| ``` | ||
|
|
||
| ### Linux (dev container — recommended) |
There was a problem hiding this comment.
This should mention how to use devcontiainers, or provide a reference to them a human or an LLM can read. If there are LLM-specific dev-container instructions, link to those so they can be read and understood by Claude.
| ### Contracts | ||
| The `contracts` MLIR dialect supports two contract types. **Static contracts** attach formal pre/postconditions to CIR operations as MLIR attributes (`contract.static`); `patchir-cir2llvm` embeds these as `!static_contract` LLVM metadata for downstream formal verification tools (KLEE, SeaHorn). **Dynamic (runtime) contracts** are implemented as C/C++ functions that are inserted at match sites (before/after calls or at function entry) and execute at runtime to validate conditions; they are specified in YAML with `type: "RUNTIME"` and a `code_file`/`function_name`. | ||
|
|
||
| ## Tools |
There was a problem hiding this comment.
This is good but again needs context about why it exists, why we build these tools, how they are used and who should use them.
Ideally we provide some built-in skills readable by both AIs and people (we do not have to do this now) that explain how to use these tools to accomplish concrete goals. We do this implicitly in tests but its better to be explicit.
| patchir-yaml-parser config.yaml --validate | ||
| ``` | ||
|
|
||
| ## Repository Layout |
|
|
||
| --- | ||
|
|
||
| ## Code Style and Conventions |
|
|
||
| --- | ||
|
|
||
| ## Verification |
There was a problem hiding this comment.
Possibly add instructions for making PRs to the repository, how to make tests for the PRs, and what level of thoroughness you expect in the PRs and tests.
|
|
||
| --- | ||
|
|
||
| ## Documentation References |
There was a problem hiding this comment.
Some of this may be also referenced in others sections but I think it is also good to have it as a separate entry like this as well.
|
@kumarak submitted review, i think this is a fantastic start, but could use more details and some formatting fixes |
|
Another update: Rename CLAUDE.md to AGENTS.md (the standard supported by Codex and Cursor) and tell CLAUDE.md to read AGENTS.md to support Claude Code |
3 participants
The pull request includes:
CLAUDE.mddescribing architecture, dependencies, build instructions, code style, verification steps, and repository layout. This provides a comprehensive overview and onboarding guide for developers..claude/rules/decomp-development.mdwith step-by-step instructions, key file mappings, build/test commands, and invariants for developing the decompilation pipeline (AST, Ghidra, patchir-decomp)..claude/rules/patch-development.mddocumenting the patch and contract development workflow, including YAML spec extension, contract dialect, CIR→LLVM lowering, and guidelines for adding new argument sources..claude/rules/pcode-serialization.mdwith instructions and key files for Ghidra P-Code JSON export, firmware testing, Docker image building, and LIT/JUnit test patterns.