Skip to content

Commit 7386741

Browse files
maciejmakowski2003maciejmakowski2003
authored
chore: added claude code setup (#967)
1 parent 5d044da commit 7386741

34 files changed

Lines changed: 4745 additions & 0 deletions

File tree

‎.claude/README.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Claude Code Setup
2+
3+
This directory contains project-specific configuration for [Claude Code](https://claude.ai/code).
4+
5+
## Structure
6+
7+
```
8+
.claude/
9+
├── settings.json # Tool permissions and MCP server configuration
10+
├── last-knowledge-update # Tracks last SHA processed by /pre-push-update
11+
├── commands/
12+
│ └── pre-push-update.md # /pre-push-update slash command
13+
├── skills/
14+
│ ├── audio-nodes/
15+
│ │ ├── SKILL.md # C++ audio node engine
16+
│ │ ├── gainnode-example.md
17+
│ │ └── maintenance.md # For /pre-push-update only
18+
│ ├── host-objects/
19+
│ │ ├── SKILL.md # JSI HostObject layer
20+
│ │ ├── examples.md
21+
│ │ └── maintenance.md
22+
│ ├── build-compilation-dependencies/
23+
│ │ ├── SKILL.md # CMake, Gradle, podspec, prebuilt libs
24+
│ │ ├── build-details.md
25+
│ │ └── maintenance.md
26+
│ ├── utilities/
27+
│ │ ├── SKILL.md # Shared C++ and TS utilities
28+
│ │ ├── api.md
29+
│ │ └── maintenance.md
30+
│ ├── native-ios/
31+
│ │ ├── SKILL.md # iOS native layer
32+
│ │ └── maintenance.md
33+
│ ├── native-android/
34+
│ │ ├── SKILL.md # Android native layer
35+
│ │ └── maintenance.md
36+
│ ├── turbo-modules/
37+
│ │ ├── SKILL.md # TurboModule/JSI wiring
38+
│ │ └── maintenance.md
39+
│ ├── web-audio-api/
40+
│ │ ├── SKILL.md # Web Audio API spec conformance
41+
│ │ └── maintenance.md
42+
│ ├── thread-safety-itc/
43+
│ │ ├── SKILL.md # Audio thread safety & ITC
44+
│ │ └── maintenance.md
45+
│ ├── post-work-checks/
46+
│ │ ├── SKILL.md # Checklist after every change
47+
│ │ └── maintenance.md
48+
│ ├── flow/
49+
│ │ ├── SKILL.md # End-to-end feature flow
50+
│ │ └── maintenance.md
51+
│ └── writing-skills/
52+
│ ├── SKILL.md # How to write and maintain skill files (meta)
53+
│ └── maintenance.md
54+
└── README.md # This file
55+
```
56+
57+
## Skills
58+
59+
Skill files are a reference library for Claude. Each skill lives in its own directory (`.claude/skills/<name>/SKILL.md`) and is **auto-loaded** by Claude Code based on the YAML frontmatter `name` and `description` fields. The description contains trigger phrases — when the conversation context matches, the skill is surfaced automatically.
60+
61+
Skills use a **three-level progressive disclosure model**:
62+
1. **Frontmatter** — always loaded; name + description with trigger phrases
63+
2. **`SKILL.md` body** — loaded when the skill is triggered; concise patterns and APIs
64+
3. **Supporting `.md` files** (e.g. `gainnode-example.md`, `build-details.md`) — linked from `SKILL.md`; loaded explicitly when deep reference is needed
65+
66+
Skills are intentionally kept concise (under 500 lines). They answer "what exists and how do I use it", not "how is it implemented". Verbose material (full code examples, deep build analysis, complete API docs for large `.hpp` files) lives alongside `SKILL.md` in the same skill directory.
67+
68+
**To update a skill manually**: edit the relevant `SKILL.md` file directly.
69+
70+
**To keep skills in sync with code automatically**: use `/pre-push-update` (see below).
71+
72+
## Maintenance Files
73+
74+
Every skill directory has a `maintenance.md` file. It maps source file path patterns to what needs checking in that skill when those paths change. This file is **not loaded during normal skill usage** — only `/pre-push-update` reads it.
75+
76+
**Purpose**: when `/pre-push-update` runs, it reads each relevant skill's `maintenance.md` to decide exactly which sections to review. Without this table, Claude has to guess — with it, the mapping is explicit and reliable.
77+
78+
**Format** (same in every `maintenance.md`):
79+
80+
```markdown
81+
# Maintenance — skill-name
82+
83+
> Used by /pre-push-update only — not loaded during skill usage.
84+
85+
| Path | What to check |
86+
|---|---|
87+
| `path/to/file.*` | What in this skill to review or update |
88+
```
89+
90+
Each `SKILL.md` ends with a single footer line: `*Maintenance: see [maintenance.md](maintenance.md).*`
91+
92+
Supporting files (e.g. `gainnode-example.md`) do **not** have their own maintenance sections — their rows are merged into the skill's `maintenance.md`.
93+
94+
**Rule**: if you add a new pattern, invariant, or code example to a skill, also add or update the relevant row in `maintenance.md` so future runs of `/pre-push-update` know to revisit it.
95+
96+
## `/pre-push-update` command
97+
98+
A slash command that reviews all commits since its last run and updates skill files to reflect what changed.
99+
100+
### How it works
101+
102+
1. `scripts/collect-knowledge-changes.sh` reads `.claude/last-knowledge-update` for the last-processed git SHA. On first run (empty file), it falls back to `HEAD~10`.
103+
2. The script outputs:
104+
- All commits in the range
105+
- **All changed files** (full stat, unfiltered) — Claude uses this to triage what is interesting
106+
- **Source diff** filtered to `*.h / *.hpp / *.cpp / *.mm / *.kt / *.ts / *.tsx` inside the tracked source directories
107+
- **Maintenance tables** — all `maintenance.md` files concatenated, so Claude knows exactly which sections to review without extra file reads
108+
3. Claude reads the output, classifies each changed path against the skill map, and makes targeted additions or corrections.
109+
4. Claude advances `.claude/last-knowledge-update` to the new HEAD SHA.
110+
111+
### When to run it
112+
113+
Run it before pushing a branch, after merging a PR, or whenever you feel the skill files may have drifted from the code. It is safe to run at any time — it only reads git history and writes to `.claude/`.
114+
115+
```bash
116+
# Inside a Claude Code session:
117+
/pre-push-update
118+
```
119+
120+
### What it updates
121+
122+
| Change type | Action |
123+
|---|---|
124+
| New audio node class | Add entry to `audio-nodes/SKILL.md` |
125+
| New HostObject pattern | Add entry to `host-objects/SKILL.md` |
126+
| New utility helper | Add entry to `utilities/SKILL.md` |
127+
| Renamed/moved class referenced in a skill | Correct the reference |
128+
| New thread-safety invariant | Add to `thread-safety-itc/SKILL.md` |
129+
| Pure formatting / test-only / CI changes | Skipped |
130+
131+
### What it does NOT do
132+
133+
- Rewrite skills from scratch
134+
- Document internal implementation details
135+
- Process binary files, lock files, or generated code
136+
- Touch anything outside `.claude/`
137+
138+
### Marker file
139+
140+
`.claude/last-knowledge-update` contains the SHA of the last commit that was successfully processed. If it is empty or the SHA is not found in history, the script falls back to `HEAD~10`. You can reset it manually by writing any valid commit SHA.
141+
142+
```bash
143+
# Reset to a specific commit (process everything since that point next run)
144+
git rev-parse <commit-ish> > .claude/last-knowledge-update
145+
146+
# Reset to process the last 20 commits next run
147+
git rev-parse HEAD~20 > .claude/last-knowledge-update
148+
```
149+
150+
### Diff limits
151+
152+
The script caps the source diff at **4000 lines**. If a batch of commits exceeds this, the diff is truncated with a warning. In that case run `/pre-push-update` more frequently, or review large refactors manually.
153+
154+
## `settings.json`
155+
156+
Defines tool permissions for Claude Code:
157+
158+
- **Always allow**: `yarn build/lint/format/test`, read-only git commands, reading all source files, writing/editing `.claude/**` and `**/CLAUDE.md`, common inspection commands (`ls`, `which`, etc.)
159+
- **Ask before**: destructive git operations (`commit`, `push`, `reset`, `checkout`, etc.), `yarn clean`
160+
- **Always deny**: force push, `rm -rf`, `sudo`, reading build artifacts and binary files
161+
162+
Also configures MCP servers:
163+
- `filesystem` — `@modelcontextprotocol/server-filesystem` pointed at the repo root
164+
- `lsp` — `mcp-language-server` using `typescript-language-server` for TS/JS code intelligence

‎.claude/commands/pre-push-update.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
Run the knowledge update process: collect all commits since the last update, analyse what changed, and update skill files and CLAUDE.md accordingly.
2+
3+
## Step 1 — Collect changes
4+
5+
Run the collection script:
6+
7+
```bash
8+
bash scripts/collect-knowledge-changes.sh
9+
```
10+
11+
If the output starts with `NO_NEW_COMMITS`, stop here and tell the user there is nothing to update.
12+
13+
## Step 2 — Triage the changed files
14+
15+
Look at the **ALL CHANGED FILES** section first. Use it to decide which changes are worth deep analysis. Classify each changed path:
16+
17+
| Path pattern | Potentially affects |
18+
|---|---|
19+
| `common/cpp/audioapi/core/` | `audio-nodes/SKILL.md` (+ `audio-nodes/gainnode-example.md`) |
20+
| `common/cpp/audioapi/HostObjects/` | `host-objects/SKILL.md` (+ `host-objects/examples.md`) |
21+
| `common/cpp/audioapi/utils/` or `dsp/` | `utilities/SKILL.md` (+ `utilities/api.md`) |
22+
| `common/cpp/audioapi/events/` or `core/utils/Audio*` | `thread-safety-itc/SKILL.md` |
23+
| `android/src/main/` | `native-android/SKILL.md` |
24+
| `ios/` | `native-ios/SKILL.md` |
25+
| `src/specs/` or `AudioAPIModule.*` | `turbo-modules/SKILL.md` |
26+
| `src/` (TypeScript) | `turbo-modules/SKILL.md` or `web-audio-api/SKILL.md` |
27+
| `CMakeLists.txt`, `*.podspec`, `*.gradle` | `build-compilation-dependencies/SKILL.md` (+ `build-compilation-dependencies/build-details.md`) |
28+
| `.claude/` | CLAUDE.md itself |
29+
30+
For each identified skill, check the **MAINTENANCE TABLES** section at the end of the script output — it contains every skill's `maintenance.md` so you can see exactly which sections to review without additional file reads.
31+
32+
**Skip a file entirely if:**
33+
- It is a test file with no new patterns (e.g. adding a test for existing behaviour)
34+
- The change is purely formatting/whitespace
35+
- It is a dependency version bump
36+
- It is CI config, example app, or lock file
37+
38+
## Step 3 — Read the source diff
39+
40+
Read the **SOURCE DIFF** section for the files you decided are interesting. For each interesting change ask:
41+
42+
1. **New API or class?** — Is there a new class, method, or utility that a developer working in this area would want to know about? If yes, add a concise entry to the relevant skill file.
43+
44+
2. **New pattern or invariant?** — Did the change reveal a non-obvious pattern, rule, or constraint (e.g. "this must always be called before X", "this field is audio-thread only")? If yes, document it in the relevant skill file.
45+
46+
3. **Broken reference?** — Does the diff rename, move, or delete something that is currently mentioned in a skill file or CLAUDE.md? If yes, correct the reference.
47+
48+
4. **New utility?** — Was a utility helper added to `utils/` or `dsp/`? If yes, add it to `utilities.md` following the existing format (brief usage note for `.h` files, inline docs for `.hpp`).
49+
50+
5. **Nothing documentable?** — If the change is purely internal implementation with no effect on the documented API, patterns, or invariants — skip it.
51+
52+
## Step 4 — Update skill files
53+
54+
Apply only targeted, minimal additions or corrections. Do **not**:
55+
- Rewrite skill files from scratch
56+
- Add documentation for every changed line
57+
- Document internal implementation details that are only useful when reading that specific file
58+
59+
Read each skill file you intend to modify before editing it.
60+
61+
## Step 5 — Advance the marker
62+
63+
Extract the `HEAD_SHA=<sha>` line from the script output. Write only that SHA (no newline, no extra text) to `.claude/last-knowledge-update`.
64+
65+
```bash
66+
# replace <sha> with the actual SHA from the last line of script output
67+
printf '%s' '<sha>' > .claude/last-knowledge-update
68+
```
69+
70+
To reset the marker to "empty" (so the next run falls back to HEAD~10), use:
71+
```bash
72+
> .claude/last-knowledge-update
73+
```
74+
(`touch` only updates the timestamp — it does **not** clear the file contents.)
75+
76+
## Step 6 — Report
77+
78+
Tell the user:
79+
- Which skill files were updated and why (one line each)
80+
- Which files were skipped and why (brief)
81+
- The new marker SHA

‎.claude/hooks/double-prompt.js‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
#!/usr/bin/env node
2+
// UserPromptSubmit hook — repeats the user's prompt as additionalContext.
3+
// Research suggests repeating the instruction improves instruction-following.
4+
5+
let data = '';
6+
process.stdin.setEncoding('utf8');
7+
process.stdin.on('data', chunk => { data += chunk; });
8+
process.stdin.on('end', () => {
9+
try {
10+
const input = JSON.parse(data);
11+
const prompt = (input.prompt || '').trim();
12+
if (prompt.length >= 500) {
13+
process.stdout.write(JSON.stringify({ additionalContext: prompt }));
14+
}
15+
} catch (_) {
16+
// parsing failed — output nothing, hook is a no-op
17+
}
18+
});

‎.claude/last-knowledge-update‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
69e3f98f9413eca44ba6ef375636873a92184587

0 commit comments

Comments
 (0)