Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions home/.chezmoiremove
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,7 @@
.claude/skills/article-writing
.claude/skills/technical-writing
.claude/skills/japanese-ai-writing-proofreader
#
# Moved to home/dot_claude/skills/zero-cost-scaling (identical body); the rule
# copy kept billing 1.7K chars on every turn on machines that applied before.
.claude/rules/zero-cost-scaling.md
12 changes: 6 additions & 6 deletions home/dot_claude/rules/db-safety.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Database Safety

A PreToolUse Bash hook (`block-destructive-db.sh`) denies known destructive database commands (`db:reset`, `prisma migrate reset`, `TRUNCATE`, `DROP DATABASE`, …) regardless of test-environment markers. Generic markers such as `NODE_ENV=test` do not prove which datasource a framework or raw client will target. The rules below cover the judgment the hook cannot make.
A PreToolUse Bash hook (`block-destructive-db.sh`) denies known destructive database commands (`db:reset`, `prisma migrate reset`, `TRUNCATE`, `DROP DATABASE`, …) regardless of test-environment markers: `NODE_ENV=test` does not prove which datasource a framework or raw client will target. The judgment the hook cannot make:

- Never wipe a database to recover from a transient error (concurrent-test schema noise, flaky migrations, stale fixtures). These are environment problems; a reset destroys dev data that lives in no seed or snapshot.
- On schema/DDL errors: stop the destructive plan, capture the exact error and command, report with that evidence, and wait for instruction. Whether a reset is acceptable is the user's call — they know what dev data they have.
- Never construct a destructive database command dynamically with parameter, brace, glob, or runtime data expansion. The hook recognizes known literal patterns and simple quote/backslash concatenation; it is an advisory guard, not a shell AST/dataflow evaluator.
- The guard may conservatively match a database runner and destructive task text across shell control operators. If a diagnostic only needs to print or search those strings, issue it as a separate Bash call.
- A test marker does not bypass the hook. To run a destructive command deliberately, run it in your own shell (the hook only blocks tool-invoked commands), or add a narrowly scoped per-project allow rule in `.claude/settings.json` for the specific command.
- Never wipe a database to recover from a transient error (concurrent-test schema noise, flaky migrations, stale fixtures). A reset destroys dev data that lives in no seed or snapshot
- On schema/DDL errors: stop, capture the exact error and command, report with that evidence, and wait for instruction. Whether a reset is acceptable is the user's call
- Never build a destructive database command from parameter, brace, glob, or runtime expansion. The hook matches known literal patterns on a quote/backslash-normalized copy; it is an advisory guard, not a shell evaluator
- The hook may match a database runner plus destructive text across shell control operators. A diagnostic that only prints or searches those strings goes in a separate Bash call
- To run a destructive command deliberately, the user runs it in their own shell (the hook only sees tool-invoked commands), or adds a narrowly scoped allow rule for that command in the project's `.claude/settings.json`
59 changes: 15 additions & 44 deletions home/dot_claude/rules/harness-engineering.md
Original file line number Diff line number Diff line change
@@ -1,56 +1,27 @@
# Harness Engineering

## Harness vs Guardrail
## Generator-Evaluator Separation

Sections in this file fall into two categories:

- **[Harness]** Pre-design — shapes how the agent runs _before_ it acts
- **[Guardrail]** Post-verification — detects deviation _after_ the agent acts

Harness is a design decision; guardrail is a mechanical check. Separating "is this pre-design or post-verification?" prevents rule bloat.

Push checks toward guardrails whenever a deterministic tool can do the job: **the stronger the mechanical verification, the more autonomy the agent can be safely given**.

## [Guardrail] Generator-Evaluator Separation

- Never self-assess quality of your own output as the final verdict
- When reviewing code you wrote, launch a separate agent that did not participate in generation
- When the main session only planned and subagents generated, the main session is a valid evaluator — no extra review subagent needed
- The evaluator should test behavior, not read implementation to form its judgment
- Never let self-assessment of your own output be the final verdict. Code you wrote is reviewed by a separate agent that did not generate it; when the main session only planned and subagents generated, the main session is a valid evaluator
- The evaluator tests behavior; it does not read the implementation to form its judgment
- Subagent reports are hypotheses, not facts: verify load-bearing claims against primary sources (run the commands, read the files) before acting on them

## [Harness] Sprint Contracts

- Before implementation: agree on concrete "done" criteria with the user
- Done criteria must be verifiable (testable assertions, observable behavior, measurable outcomes)
- If criteria cannot be verified automatically, state which require manual verification
- For multi-turn implementation tasks, encode the contract via `/goal <criteria>` so the harness tracks completion across turns (shows live elapsed/turns/tokens overlay)

## [Guardrail] Review Discipline

### Giving reviews
## Sprint Contracts

- Review only changed code. Do not flag pre-existing issues unless they interact with changes
- Classify findings: CRITICAL (blocks ship) / IMPORTANT (should fix) / LOW (nice-to-have)
- Drop LOW findings. Present only CRITICAL and IMPORTANT
- For each fix: state whether it addresses the root cause or is a workaround
- Before implementing, agree on concrete "done" criteria with the user: testable assertions, observable behavior, measurable outcomes. Say which require manual verification
- For multi-turn implementation, encode the contract via `/goal <criteria>` so the harness tracks completion across turns

### Receiving reviews
## Review Discipline

- Do not blindly implement feedback — first verify the suggestion is technically correct
- If a reviewer's suggestion would break something, say so with evidence
- If feedback is vague or unclear, ask for clarification instead of guessing intent
- No performative agreement ("great suggestion!") — just evaluate and act
- Giving: review only changed code, flagging pre-existing issues only when they interact with the change. Classify CRITICAL (blocks ship) / IMPORTANT (should fix) / LOW and present only CRITICAL and IMPORTANT. For each fix, say whether it addresses the root cause or is a workaround
- Receiving: verify a suggestion is technically correct before implementing it; if it would break something, say so with evidence; ask when feedback is vague. No performative agreement

## [Guardrail] Oscillation Guard
## Oscillation Guard

- If a fix reverts a previous fix (A -> B -> A pattern), stop and escalate to the user
- When stuck in a fix loop (3+ attempts at the same issue), re-plan instead of retrying
- Maximum 5 review-fix iterations before presenting current state to user
- A fix that reverts a previous fix (A -> B -> A): stop and escalate to the user
- 3+ attempts at the same issue: re-plan instead of retrying. Maximum 5 review-fix iterations before presenting the current state to the user

## [Harness] Decision Records
## Decision Records

- Record non-trivial technical decisions as ADRs (Architecture Decision Records)
- Check for existing ADR directory (`docs/adr/`, `docs/decisions/`, `adr/`, etc.) and follow that convention. If none exists, recommend `docs/adr/`
- Before making architectural choices, read existing ADRs for prior decisions and constraints
- Write ADRs in English; file naming `NNNN-short-description.md`; sections: Status / Context / Decision / Consequences
- Record non-trivial technical decisions as ADRs. Follow the repo's existing ADR directory convention (`docs/adr/`, `docs/decisions/`, `adr/`, …); if none exists, recommend `docs/adr/`. Read existing ADRs before making architectural choices
- English; file naming `NNNN-short-description.md`; sections: Status / Context / Decision / Consequences
2 changes: 1 addition & 1 deletion home/dot_claude/rules/harness-meta.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Where to place a new constraint, by violation history and reversibility:

- Skip levels when the action is irreversible — go straight to L3+ instead of trusting prose
- Prefer machine-checkable enforcement (L3/L4) over instructions (L1/L2) whenever a deterministic check is possible
- See `harness-engineering.md` for why this matches "the stronger the mechanical verification, the more autonomy"
- Harness (pre-design that shapes how the agent runs) vs guardrail (post-hoc mechanical check): push checks toward guardrails whenever a deterministic tool can do the job. The stronger the mechanical verification, the more autonomy the agent can safely be given

## Harness Simplification

Expand Down
24 changes: 8 additions & 16 deletions home/dot_claude/rules/markdown-formatting.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,19 @@
# Markdown Formatting

Language-independent formatting rules for Markdown output (responses, PR bodies, docs).
Language-independent rules for Markdown output (responses, PR bodies, docs).

- Don't hardcode numbers at the start of headings or list items. If order matters, let Markdown's ordered-list syntax (`1.` `2.`) render the numbering; don't type the numerals into the body text yourself.
- Don't type numerals into headings or list items. If order matters, use ordered-list syntax (`1.` `2.`) and let Markdown render the numbering

## Line breaks in prose

Prose has **no column limit** and is **not hard-wrapped** by default. Write one paragraph per line and let the editor/renderer soft-wrap. A hard wrap gains nothing in rendered Markdown (CommonMark collapses a soft break to a space) and is a footgun on hard-break surfaces (below).

- **Never wrap hard-break surfaces**: GitHub issue / PR / comment bodies render every single newline as a `<br>`, so a wrapped paragraph shows as jagged forced breaks. Write them as long unwrapped lines with a blank line between paragraphs. (Tables and code blocks are not prose — leave them.)
- **Follow the repo's prose convention when it declares one**: Prettier `proseWrap`, or an existing consistently-wrapped corpus (e.g. these rule files). Match it.
- [Semantic Line Breaks](https://sembr.org/) (one sentence per line) is **opt-in** — worth it only where the repo wants sentence-granularity prose diffs, never the global default. When wrapping, break only at sentence boundaries (。..!?!?), never mid-clause. Japanese: a mid-sentence wrap can render as a bogus half-width space (CJK segment-break removal is unevenly implemented), so the sentence boundary is the only safe break.

**Code line length** is not governed here — it follows each language's own formatter / linter (`.editorconfig`, `.stylua.toml`, Prettier, `shfmt`, etc.), never a Markdown-wide column rule.
- Prose has **no column limit** and is **not hard-wrapped**: one paragraph per line, soft-wrapped by the renderer. CommonMark collapses a soft break to a space, so wrapping gains nothing
- **Never wrap GitHub issue / PR / comment bodies**: every newline renders as `<br>`. Tables and code blocks are not prose
- Follow the repo's declared prose convention (Prettier `proseWrap`, a consistently wrapped corpus) when there is one. [Semantic Line Breaks](https://sembr.org/) are opt-in per repo, never the default; when wrapping, break only at sentence boundaries (。..!?!?), since a mid-sentence wrap in Japanese can render a bogus half-width space
- Code line length follows each language's own formatter, never a Markdown rule

## Diagrams: mermaid in artifacts, ASCII in chat

Use mermaid in **written artifacts only** — PR bodies, ADRs, README, technical docs, .md files — where GitHub, Obsidian, VS Code preview, etc. render it as a real diagram. In chat/terminal responses it is the reverse: mermaid does not render there, so use ASCII art, prose, or short bullet lists instead.
Use mermaid only in written artifacts (PR bodies, ADRs, README, `.md` files) where GitHub, Obsidian, or VS Code render it. Chat/terminal responses do not render it: use ASCII art, prose, or short bullets there.

### When to diagram

Expand All @@ -31,9 +28,4 @@ A diagram is due when prose would make the reader sketch it themselves:

### Authoring rules

- ≤ ~10 nodes per diagram; split larger into multiple
- Concrete node labels (`UserService`, not `ServiceA`)
- Show before/after side-by-side for structural refactors
- Prefer `LR` for pipelines, `TD` for hierarchies

For embedding in GitHub PR bodies safely (backslash-escape pitfall), see `gh-pr-body.md`.
≤ ~10 nodes per diagram (split larger ones); concrete node labels (`UserService`, not `ServiceA`); `LR` for pipelines, `TD` for hierarchies. For embedding in GitHub PR bodies safely, see `gh-pr-body.md`.
Loading
Loading