From b0c0e756371de12638e1d69e9cdc9f9c0e5c1b6e Mon Sep 17 00:00:00 2001
From: LittleYellow <crazytea@gmail.com>
Date: Sat, 27 Jun 2026 07:06:16 +0800
Subject: [PATCH] chore: persist db data to host path and add agent
 instructions

- docker-compose: mount ~/tcms-db-data for the sqlite database
- add CLAUDE.md agent coding guidelines

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CLAUDE.md           | 84 +++++++++++++++++++++++++++++++++++++++++++++
 docker-compose.yaml |  2 +-
 2 files changed, 85 insertions(+), 1 deletion(-)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..7d5e27d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,84 @@
+# CLAUDE.md — Agent Instructions
+
+Behavioral guidelines for AI coding agents. Merges Andrej Karpathy's
+LLM coding-pitfall observations with the Ponytail minimalism ladder.
+
+**Tradeoff:** bias toward caution *and* minimalism. On trivial tasks,
+use judgment — don't ask when the answer is obvious, just write the
+smallest thing that works.
+
+---
+
+## 1. Think before coding
+
+Don't assume. Don't hide confusion. Surface tradeoffs.
+
+- State assumptions explicitly.
+- If interpretations genuinely diverge, ask ONE clarifying question.
+  Otherwise take the minimal reading, write the assumption as an inline
+  comment, and proceed — do not stall.
+- If a simpler approach exists, say so. Push back when warranted.
+
+## 2. Write the least code that works (the ladder)
+
+Before writing any code, stop at the FIRST rung that solves the task:
+
+1. **Skip it** — is the feature even needed? (YAGNI)
+2. **Stdlib** — does the standard library already do this?
+3. **Native** — does the platform/runtime have it built in?
+4. **Existing dependency** — can something already installed do the job?
+5. **One line** — can it be one line?
+6. **Minimum** — only now, write the least code that works.
+
+No features beyond what was asked. No abstractions for single-use code.
+No speculative flexibility or configurability. No error handling for
+impossible scenarios. If you wrote 200 lines and it could be 50, rewrite.
+
+Test: "Would a senior engineer call this overcomplicated?" If yes, simplify.
+
+## 3. Where laziness stops
+
+Section 2 does NOT apply to these — here, do it properly:
+
+- Input validation at trust boundaries.
+- Error handling that prevents data loss.
+- Security.
+- Accessibility.
+- Calibration real hardware needs (clocks drift, sensors read off — the
+  platform is never the spec ideal).
+- Anything the user explicitly requested.
+
+## 4. Mark and verify your shortcuts
+
+Lazy code without a check is unfinished.
+
+- Mark every intentional simplification with a `ponytail:` comment. If the
+  shortcut has a known ceiling (global lock, O(n²) scan, naive heuristic),
+  the comment names the ceiling and the upgrade path.
+- Non-trivial logic leaves behind ONE runnable check — the smallest thing
+  that fails if the logic breaks (an assert-based self-check or one small
+  test file; no frameworks, no fixtures).
+- Turn the task into a verifiable goal and loop until it passes:
+  - "Add validation" → write tests for invalid inputs, then make them pass.
+  - "Fix the bug" → write a test that reproduces it, then make it pass.
+  - "Refactor X" → ensure tests pass before and after.
+
+For multi-step tasks, state a brief plan: `1. step → verify: check`.
+
+## 5. Surgical changes
+
+Touch only what you must. Clean up only your own mess.
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor what isn't broken. Match existing style.
+- Remove imports/variables/functions that YOUR changes made unused.
+- Pre-existing dead code: mention it, don't delete it (unless asked).
+
+Test: every changed line traces directly to the user's request.
+
+---
+
+**Working if:** fewer unnecessary changes in diffs, fewer rewrites from
+overcomplication, clarifying questions come *before* implementation rather
+than after mistakes, and intentional shortcuts are visible (`ponytail:`)
+rather than silent.
diff --git a/docker-compose.yaml b/docker-compose.yaml
index 74cfdf3..95955ee 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -9,7 +9,7 @@ services:
       - SECRET_KEY=your_secret_key_here
       - IS_DEMO=false # set to true to seed the database
     volumes:
-      - db-data:/app/backend/database
+      - ~/tcms-db-data:/app/backend/database
       - ./backend/public/uploads:/app/backend/public/uploads
 
 volumes: