Restructure & document the shared Claude config (project/ code-guide)#4035
Open
Leiyks wants to merge 10 commits into
Open
Restructure & document the shared Claude config (project/ code-guide)#4035Leiyks wants to merge 10 commits into
Leiyks wants to merge 10 commits into
Conversation
Add a portable, repo-side convention so each developer can keep personal Claude config alongside the shared team config without committing it, and fold project-level knowledge into the committed common config. - .claude/.gitignore: ignore per-developer paths (personal/, commands/, scripts/, skills/omc-reference/, settings.local.json, worktrees/, .omc/) in place; keep personal/README.md committed. Previously this relied on each developer's global gitignore, which isn't portable and silently hid new shared files. - .claude/personal/: git-ignored drop zone for per-developer config; CLAUDE.md optionally imports personal/CLAUDE.md if present. - .claude/project.md: project knowledge (overview, layout, architecture, INI, conventions) in the terse house style, cross-referencing the existing build/CI/debug docs instead of duplicating them. Reflects the ext/ -> tracer/ split (#3912); versions reference VERSION / Cargo.toml / rust-toolchain.toml rather than being pinned inline. - CLAUDE.md: link general.md, project.md, ci/index.md and import personal.
|
Plain markdown links in CLAUDE.md are not injected into context by Claude Code — only @-imports are. Import general.md and project.md so the shared operating rules and project knowledge are always loaded alongside each developer's personal config. ci/index.md stays a link (large on-demand CI reference).
Leiyks
force-pushed
the
leiyks/claude-config-consolidation
branch
from
b315fbb to
71979cc
Compare
… commands Addresses PR review feedback: - .claude/.gitignore: commands/ is now personal-by-default via `/commands/*` (instead of ignoring the whole dir), so the team CAN commit shared commands by un-ignoring them while personal ones stay ignored. Claude Code discovers commands by filesystem regardless of git status, so both coexist. - Scripts: shared helper scripts moved into .claude/scripts/ (dd_php_release_url, find_map_region.py, parse_ucontext.py); personal scripts go in .claude/scripts/local/ (git-ignored). crash-analysis skill refs updated. - Debugging docs grouped under .claude/debugging/ with an index.md (like ci/): gdb.md, appsec-integration.md (was debugging.md), system-tests.md (was debugging-system-tests.md). All inbound/outbound links updated. Note: ci/ keeps its own co-located tooling (dockerh, check-ci, ...) since those are referenced throughout the ci/ docs as a self-contained module.
Personal skills live in .claude/skills/ alongside shared ones (Claude Code discovers by filesystem, ignoring git status). Their dir name is the skill name, so there's no generic pattern; document that each dev ignores their own personal skill dirs in .git/info/exclude (per-clone) instead of publishing personal skill names into the committed shared config.
Leiyks
force-pushed
the
leiyks/claude-config-consolidation
branch
from
0f7c2a6 to
35d2e26
Compare
Personal Claude config now lives entirely in ~/.claude (global), so the repo's .claude/ is purely shared team config: - Remove .claude/personal/ (README) and the @.claude/personal/CLAUDE.md import from CLAUDE.md. - Slim .claude/.gitignore to just local/runtime artifacts (settings.local.json, worktrees/, .omc/); document that personal config goes in ~/.claude.
The repo .claude/ carries no ignore file now — it's purely shared config. Local/runtime artifacts are handled outside the shared config: settings.local.json via the repo root .gitignore, and per-developer tooling output (OMC .omc/, Claude Code agent worktrees/checkpoints/etc.) via each dev's own global ~/.gitignore.
Turn the single project.md into a ci/-style folder: a concise always-imported index.md (overview, layout, subsystem map, architecture summary, config, conventions, pointers) plus one terse orientation file per subsystem — ext, tracer, userland (src/), components (+components-rs/ZAI), sidecar, appsec, profiling. Each covers what it is / key files & dirs / how it fits / gotchas, cross-linked, with build/CI/debug content linked out (not duplicated). Produced via an analyze→write→review pass over the actual source: per-subsystem code analysis, drafting, then a source-accuracy + house-style review. Versions are referenced by source-of-truth (VERSION, Cargo.toml, rust-toolchain.toml); no hardcoded versions or source line numbers. CLAUDE.md now imports project/index.md.
…NTRIBUTING Targeted depth-increase (on-demand area files only; index stays lean): - tracer.md: ordered span→upload data-flow (RINIT → headers → span create → uhook → close → sampling → serializer → auto_flush → sidecar/coms → agent). - ext.md: fix the incorrect "MSHUTDOWN tears down in reverse" claim — it isn't (sidecar shuts down late, after config is freed); tighten MINIT/RINIT/RSHUTDOWN ordering (logging-first, zend_extension registration, dd_rinit_once). - sidecar.md: submit→upload flow (serialize → send_traces_to_sidecar → IPC → TraceFlusher batches ~5s/~1MB → agent upload; fork preserves session ID). - index.md: link architecture.md (background sender / components / version code) and CONTRIBUTING.md (setup/testing) from Pointers. Produced via the OMC analyze→write→review pipeline over live source; verified accurate (flush thresholds, ordering, function anchors). No line numbers.
Leiyks
changed the title
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 95476d8465
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
All four verified against live source: - appsec.md: C++ helper client/runner/engine/service are .cpp/.hpp files, not dirs (only network/, remote_config/, subscriber/ are dirs). - appsec.md: the helper is enabled via the sidecar — ext/sidecar.c calls the appsec module's dd_appsec_maybe_enable_helper -> ddog_sidecar_enable_appsec (resolved Rust/C++ path) before ddappsec's first RINIT — not spawned by ddappsec MINIT/RINIT. - tracer.md + index.md: the sidecar sender is only the default on PHP 8.3+ / Windows (DD_SIDECAR_TRACE_SENDER_DEFAULT); on PHP 7.0-8.2 the in-process coms.c sender is the default. - components.md: drop container_id from the component list — it's a stale build-artifact dir with no source; container ID is in the Rust bridge (ddtrace_get_container_id).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Cleans up and documents the repo's shared
.claude/Claude Code config. The.claude/tree is now purely shared team config — personal, per-developerconfig is kept out of the repo entirely (each dev keeps it in their own
~/.claude), so there's no in-repo personal machinery to maintain.Changes
Entry point (
CLAUDE.md)@imports the always-on shared config (general.md,project/index.md) andlinks
ci/index.md(large, on-demand). Only@imports are auto-loaded byClaude Code — plain links are not — so the always-needed docs are imported
while the big CI reference stays on-demand. Personal config is explicitly out
of the repo.
New
project/code-guide (aci/-style folder)project/index.md— concise, always-imported hub: overview, layout,subsystem map, architecture summary, config/INI, conventions, pointers.
ext,tracer,userland(
src/),components(+components-rs/+ ZAI),sidecar,appsec,profiling— each with what it is / key files & dirs / how it fits /gotchas, plus an explicit data-flow for the trace / ext / sidecar paths.
ci/,debugging/), notduplicated. Reflects the
ext/→tracer/split (Split the tracer parts off from ext directory #3912); versions arereferenced by source-of-truth (
VERSION,Cargo.toml,profiling/rust-toolchain.toml) — no hardcoded versions or source linenumbers. Links the deep docs (
architecture.md,CONTRIBUTING.md).Folder cleanup
debugging/with an index (gdb.md,appsec-integration.md,system-tests.md).scripts/(dd_php_release_url,find_map_region.py,parse_ucontext.py); references updated.How the code-guide was built
The
project/docs were generated by reading the actual source: aper-subsystem analysis pass → drafting → an independent source-accuracy +
house-style review pass. That review caught and fixed real issues (e.g. a wrong
"MSHUTDOWN tears down in reverse of MINIT" claim, and a reference to a
deleted file).
Verified
hallucinated paths); no hardcoded versions or source line numbers.
.claude/contains only shared team config — no personal files.