docs: add Working discipline section to CLAUDE.md #394

Merged

james merged 1 commit from docs-working-discipline into main 2026-06-30 14:00:11 +00:00

Conversation 2 Commits 1 Files changed 1 +27

james commented 2026-06-30 13:58:54 +00:00

Owner

Copy link

Adds a short Working discipline section to CLAUDE.md (between "Working in this repo" and "Out of scope"), encoding how-to-change-code rules adapted from the widely-circulated Karpathy-attributed CLAUDE.md.

Kept deliberately small — only the rules that aren't already covered by an ADR or base agent behavior, and that map to mistakes that have actually cost this project:

• Read before writing — Carol is convention-dense; mimic the neighboring entity/route/screen instead of the generic approach (which usually trips a load-bearing convention).
• Fix bugs test-first — reproduce in the both-engine matrix first; root cause, not symptom.
• Minimum code for the ticket — no speculative abstraction; re-scope if a diff grows past its ticket.
• Surgical diffs — touch only what's needed; no reformatting; orphaned dead code only.
• State assumptions / ask when ambiguous — surface options before building.
• Done means verified — gates green by your own hand; deferred work gets a follow-up ticket.

Intentionally omits the dependency-hygiene and four-rule-template items already governed harder by ADR-0009/0022, the install-script allowlist, and the existing Conventions section. Provenance of the source document is community-attributed and unverified — this PR adapts the few high-signal rules rather than copying it wholesale.

Docs-only; no code or behavior change.

🤖 Generated with Claude Code

Adds a short **Working discipline** section to `CLAUDE.md` (between "Working in this repo" and "Out of scope"), encoding how-to-change-code rules adapted from the widely-circulated Karpathy-attributed `CLAUDE.md`. Kept deliberately small — only the rules that **aren't already** covered by an ADR or base agent behavior, and that map to mistakes that have actually cost this project: - **Read before writing** — Carol is convention-dense; mimic the neighboring entity/route/screen instead of the generic approach (which usually trips a load-bearing convention). - **Fix bugs test-first** — reproduce in the both-engine matrix first; root cause, not symptom. - **Minimum code for the ticket** — no speculative abstraction; re-scope if a diff grows past its ticket. - **Surgical diffs** — touch only what's needed; no reformatting; orphaned dead code only. - **State assumptions / ask when ambiguous** — surface options before building. - **Done means verified** — gates green by your own hand; deferred work gets a follow-up ticket. Intentionally omits the dependency-hygiene and four-rule-template items already governed harder by ADR-0009/0022, the install-script allowlist, and the existing Conventions section. Provenance of the source document is community-attributed and unverified — this PR adapts the few high-signal rules rather than copying it wholesale. Docs-only; no code or behavior change. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

james added 1 commit 2026-06-30 13:58:54 +00:00

docs: add Working discipline section to CLAUDE.md ... 83c6a370c7

Encodes a small set of how-to-change-code rules adapted from the
widely-circulated Karpathy-attributed CLAUDE.md, kept only where they
aren't already covered by an ADR or base agent behavior and where they
map to mistakes that have actually cost this project:

- Read before writing (Carol is convention-dense; mimic the local pattern)
- Fix bugs test-first, root cause not symptom
- Minimum code for the ticket; surgical diffs; no reformatting
- State assumptions / ask when ambiguous
- Done means gates green by your own hand; deferred work gets a ticket

Deliberately omits the dependency-hygiene and four-rule-template items
already governed by ADR-0009/0022, the install-script allowlist, and the
existing Conventions section.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

james merged commit 454c06770e into main 2026-06-30 14:00:11 +00:00

james deleted branch docs-working-discipline 2026-06-30 14:00:11 +00:00

james referenced this pull request from a commit 2026-06-30 14:00:13 +00:00

Merge pull request 'docs: add Working discipline section to CLAUDE.md' (#394) from docs-working-discipline into main

forgejo-actions commented 2026-06-30 14:04:02 +00:00

Copy link

Trivy (container image)

Threshold: high  ·  Total findings: 135  ·  At/above threshold: 2

critical	high	medium	low
0	2	62	71

severity	id	package	installed / range	fix
high	CVE-2026-54369	libacl1	2.3.1-3	none
high	CVE-2026-54371	libattr1	1:2.5.1-4	none

<!-- scanner-comment: trivy --> ### Trivy (container image) **Threshold:** `high` &nbsp;·&nbsp; **Total findings:** 135 &nbsp;·&nbsp; **At/above threshold:** 2 | critical | high | medium | low | |---:|---:|---:|---:| | 0 | 2 | 62 | 71 | | severity | id | package | installed / range | fix | |---|---|---|---|---| | high | [CVE-2026-54369](https://avd.aquasec.com/nvd/cve-2026-54369) | libacl1 | 2.3.1-3 | none | | high | [CVE-2026-54371](https://avd.aquasec.com/nvd/cve-2026-54371) | libattr1 | 1:2.5.1-4 | none |

forgejo-actions commented 2026-06-30 14:04:16 +00:00

Copy link

📊 Test coverage

Patch coverage: no testable lines changed.

Overall (app/, lib/, db/, excluding UI per ADR-0019):

Metric	Value	Soft target
Lines	79.7% ✅	≥ 50%
Branches	71.6% ⚠️	≥ 75%
Functions	81.2%	informational

Soft thresholds per ADR-0019. Coverage is informational and does not block merge.

<!-- coverage-comment --> ## 📊 Test coverage **Patch coverage:** no testable lines changed. **Overall** (`app/`, `lib/`, `db/`, excluding UI per ADR-0019): | Metric | Value | Soft target | |---|---|---| | Lines | 79.7% ✅ | ≥ 50% | | Branches | 71.6% ⚠️ | ≥ 75% | | Functions | 81.2% | informational | Soft thresholds per [ADR-0019](docs/adr/0019-coverage-soft-targets.md). Coverage is informational and does not block merge.

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area:auth

Authentication and authorization

  

area:ci

Forgejo Actions, build, test, security, release

  

area:db

Database abstraction, migrations, persistence

  

area:infra

Containerization, deployment, foundational tooling

  

area:native

React Native app (Android + Linux Flatpak)

  

area:pwa

PWA / web frontend

  

area:service

Backend service, API routes, persistence

  

epic

High-level tracker; links several feature tickets

  

feature

A user-facing feature

  

foundation

Foundational work that other tickets build on

No labels

area:auth

area:ci

area:db

area:infra

area:native

area:pwa

area:service

epic

feature

foundation

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

james/carol!394

No description provided.