claudeos-core 2.4.1 → 2.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.de.md +172 -174
  3. package/README.es.md +161 -163
  4. package/README.fr.md +159 -161
  5. package/README.hi.md +166 -168
  6. package/README.ja.md +166 -168
  7. package/README.ko.md +139 -141
  8. package/README.md +55 -57
  9. package/README.ru.md +173 -175
  10. package/README.vi.md +169 -171
  11. package/README.zh-CN.md +168 -170
  12. package/package.json +1 -1
package/README.vi.md CHANGED
@@ -7,58 +7,40 @@
7
7
  [![license](https://img.shields.io/npm/l/claudeos-core.svg?color=blue)](LICENSE)
8
8
  [![downloads](https://img.shields.io/npm/dm/claudeos-core.svg?logo=npm&color=blue&label=downloads)](https://www.npmjs.com/package/claudeos-core)
9
9
 
10
- **Để Claude Code tuân theo các quy ước của _dự án bạn_ ngay từ lần đầu — không phải các mặc định chung chung.**
11
-
12
- Một deterministic Node.js scanner đọc mã nguồn của bạn trước; sau đó pipeline Claude 4-pass viết toàn bộ — `CLAUDE.md` + `.claude/rules/` tự động nạp + standards + skills + L4 memory. 10 ngôn ngữ đầu ra, 5 validator hậu sinh, và một path allowlist tường minh ngăn LLM bịa ra các tệp hoặc framework không có trong code của bạn.
13
-
14
- Hoạt động trên [**12 stack**](#supported-stacks) (bao gồm monorepo) — một lệnh `npx` duy nhất, không cần cấu hình, resume-safe, idempotent.
10
+ **Một CLI đọc trực tiếp source code dự án rồi tự sinh ra `CLAUDE.md` cùng `.claude/rules/`. Bộ công cụ gồm Node.js scanner, pipeline 4-pass cho Claude và 5 validator. Hỗ trợ 12 stack, 10 ngôn ngữ, và không bao giờ tạo ra đường dẫn không có trong code.**
15
11
 
16
12
  ```bash
17
13
  npx claudeos-core init
18
14
  ```
19
15
 
16
+ Có thể dùng ngay với [**12 stack**](#supported-stacks), kể cả monorepo. Một câu lệnh là đủ, không cần cấu hình, chạy giữa chừng dừng lại vẫn tiếp tục được, và chạy nhiều lần cũng an toàn.
17
+
20
18
  [🇺🇸 English](README.md) · [🇰🇷 한국어](README.ko.md) · [🇨🇳 中文](README.zh-CN.md) · [🇯🇵 日本語](README.ja.md) · [🇪🇸 Español](README.es.md) · [🇮🇳 हिन्दी](README.hi.md) · [🇷🇺 Русский](README.ru.md) · [🇫🇷 Français](README.fr.md) · [🇩🇪 Deutsch](README.de.md)
21
19
 
22
20
  ---
23
21
 
24
- ## Công cụ này là gì?
25
-
26
- Bạn đang dùng Claude Code. Nó mạnh mẽ, nhưng mỗi phiên đều bắt đầu mới — không có ký ức về cách _dự án của bạn_ được tổ chức. Vì vậy nó fallback về các mặc định "tốt nói chung" mà hiếm khi khớp với những gì đội bạn thực sự làm:
27
-
28
- - Đội bạn dùng **MyBatis**, nhưng Claude lại sinh JPA repository.
29
- - Response wrapper của bạn là `ApiResponse.ok()`, nhưng Claude lại viết `ResponseEntity.success()`.
30
- - Package của bạn là layer-first (`controller/order/`), nhưng Claude lại tạo domain-first (`order/controller/`).
31
- - Lỗi của bạn đi qua centralized middleware, nhưng Claude rải `try/catch` ở mọi endpoint.
22
+ ## Đây là gì?
32
23
 
33
- Bạn muốn có một bộ `.claude/rules/` cho từng dự án — Claude Code tự động nạp mỗi phiên — nhưng viết tay những rule đó cho mỗi repo mới mất hàng giờ, và chúng drift theo sự tiến hóa của code.
24
+ Mỗi khi mở phiên mới, Claude Code lại rơi về mặc định của framework. Team đang dùng **MyBatis** thì Claude vẫn cứ viết JPA. Wrapper dự án là `ApiResponse.ok()`, Claude lại quen tay gõ `ResponseEntity.success()`. Package theo layer-first, Claude lại sinh ra kiểu domain-first. Viết tay `.claude/rules/` cho từng repo thì chữa được tạm thời, nhưng code đổi vài lần là rules cũng lệch theo.
34
25
 
35
- **ClaudeOS-Core viết chúng cho bạn, từ chính mã nguồn thực tế của bạn.** Một deterministic Node.js scanner đọc dự án bạn trước (stack, ORM, layout package, quy ước, đường dẫn tệp). Sau đó pipeline Claude 4-pass biến các sự kiện đã trích xuất thành một bộ tài liệu hoàn chỉnh:
26
+ **ClaudeOS-Core sinh lại toàn bộ tài liệu này một cách nhất quán, đọc thẳng từ source code thật.** Đầu tiên, một Node.js scanner duyệt dự án để chốt stack, ORM, cấu trúc package và đường dẫn file. Tiếp đó pipeline 4-pass của Claude viết toàn bộ tài liệu: `CLAUDE.md`, `.claude/rules/` auto-load, standards và skills. Mọi pass đều bị khoá trong một allowlist đường dẫn tường minh, LLM không thoát ra được. Cuối cùng, năm validator soi lại kết quả trước khi xuất.
36
27
 
37
- - **`CLAUDE.md`** — chỉ mục dự án mà Claude đọc ở mỗi phiên
38
- - **`.claude/rules/`** — rules tự động nạp theo category (`00.core` / `10.backend` / `20.frontend` / `30.security-db` / `40.infra` / `60.memory` / `70.domains` / `80.verification`)
39
- - **`claudeos-core/standard/`** — tài liệu tham chiếu ("vì sao" sau mỗi rule)
40
- - **`claudeos-core/skills/`** — pattern tái sử dụng (CRUD scaffolding, page template)
41
- - **`claudeos-core/memory/`** — decision log + failure pattern lớn lên cùng dự án
28
+ Nhờ vậy, cùng input thì luôn ra cùng output, byte-identical ở cả 10 ngôn ngữ, và không bịa ra đường dẫn không có trong code. (Xem chi tiết ở phần [Điểm khác biệt](#điểm-khác-biệt) bên dưới.)
42
29
 
43
- Vì scanner trao cho Claude một path allowlist tường minh, LLM **không thể bịa ra các tệp hoặc framework không có trong code của bạn**. Năm validator hậu sinh (`claude-md-validator`, `content-validator`, `pass-json-validator`, `plan-validator`, `sync-checker`) xác minh đầu ra trước khi ship — language-invariant, vì vậy cùng một bộ rule áp dụng dù bạn sinh bằng tiếng Anh, tiếng Hàn hay 8 ngôn ngữ còn lại.
44
-
45
- ```
46
- Trước: Bạn → Claude Code → code "tốt nói chung" → sửa thủ công mỗi lần
47
- Sau: Bạn → Claude Code → code khớp với DỰ ÁN CỦA BẠN → dùng luôn
48
- ```
30
+ Với các dự án chạy lâu dài, công cụ còn seed thêm một [Memory Layer](#memory-layer-tùy-chọn-cho-dự-án-dài-hạn) riêng.
49
31
 
50
32
  ---
51
33
 
52
- ## Xem trên một dự án thật
34
+ ## Xem trên dự án thực tế
53
35
 
54
- Chạy trên [`spring-boot-realworld-example-app`](https://github.com/gothinkster/spring-boot-realworld-example-app) — Java 11 · Spring Boot 2.6 · MyBatis · SQLite · 187 source files. Kết quả: **75 generated files**, tổng thời gian **53 phút**, mọi validator ✅.
36
+ Chạy thử trên [`spring-boot-realworld-example-app`](https://github.com/gothinkster/spring-boot-realworld-example-app). Dự án dùng Java 11, Spring Boot 2.6, MyBatis, SQLite với 187 file source. Kết quả: **75 file được sinh ra**, tổng thời gian **53 phút**, mọi validator đều ✅.
55
37
 
56
38
  <p align="center">
57
39
  <img src="docs/assets/spring-boot-realworld-demo.gif" alt="ClaudeOS-Core init running on spring-boot-realworld-example-app — stack detection, 4-pass pipeline, validators, completion summary" width="769">
58
40
  </p>
59
41
 
60
42
  <details>
61
- <summary><strong>📺 Đầu ra terminal (bản text, để tìm kiếm và sao chép)</strong></summary>
43
+ <summary><strong>Output terminal (bản text, để tiện tìm kiếm và copy)</strong></summary>
62
44
 
63
45
  ```text
64
46
  ╔════════════════════════════════════════════════════╗
@@ -93,18 +75,18 @@ Chạy trên [`spring-boot-realworld-example-app`](https://github.com/gothinkste
93
75
  [██████████░░░░░░░░░░] 50% (2/4)
94
76
 
95
77
  [6] Pass 3 — Generating all files...
96
- 🚀 Pass 3 split mode (3a → 3b → 3c → 3d-aux)
78
+ Pass 3 split mode (3a → 3b → 3c → 3d-aux)
97
79
  ✅ 3a complete (2m 57s) — pass3a-facts.md (187-path allowlist)
98
80
  ✅ 3b complete (18m 49s) — CLAUDE.md + 19 standards + 20 rules
99
81
  ✅ 3c complete (12m 35s) — 13 skills + 9 guides
100
82
  ✅ 3d-aux complete (3m 18s) — database/ + mcp-guide/
101
- 🎉 Pass 3 split complete: 4/4 stages successful
83
+ Pass 3 split complete: 4/4 stages successful
102
84
  [███████████████░░░░░] 75% (3/4)
103
85
 
104
86
  [7] Pass 4 — Memory scaffolding...
105
- 📦 Pass 4 staged-rules: 6 rule files moved to .claude/rules/
87
+ Pass 4 staged-rules: 6 rule files moved to .claude/rules/
106
88
  ✅ Pass 4 complete (5m)
107
- 📋 Gap-fill: all 12 expected files already present
89
+ Gap-fill: all 12 expected files already present
108
90
  [████████████████████] 100% (4/4)
109
91
 
110
92
  ╔═══════════════════════════════════════╗
@@ -133,7 +115,7 @@ Chạy trên [`spring-boot-realworld-example-app`](https://github.com/gothinkste
133
115
  </details>
134
116
 
135
117
  <details>
136
- <summary><strong>📄 Nội dung kết thúc trong <code>CLAUDE.md</code> của bạn (trích đoạn thực tế — Section 1 + 2)</strong></summary>
118
+ <summary><strong>Phần thực sự đi vào <code>CLAUDE.md</code> của bạn (trích đoạn thật — Section 1 + 2)</strong></summary>
137
119
 
138
120
  ```markdown
139
121
  # CLAUDE.md — spring-boot-realworld-example-app
@@ -142,7 +124,7 @@ Chạy trên [`spring-boot-realworld-example-app`](https://github.com/gothinkste
142
124
  > Java 11 + Spring Boot 2.6, exposing both REST and GraphQL endpoints
143
125
  > over a hexagonal MyBatis persistence layer.
144
126
 
145
- ## 1. Role Definition
127
+ #### 1. Role Definition
146
128
 
147
129
  As the senior developer for this repository, you are responsible for
148
130
  writing, modifying, and reviewing code. Responses must be written in English.
@@ -150,7 +132,7 @@ A Java Spring Boot REST + GraphQL API server organized around a hexagonal
150
132
  (ports & adapters) architecture, with a CQRS-lite read/write split inside
151
133
  an XML-driven MyBatis persistence layer and JWT-based authentication.
152
134
 
153
- ## 2. Project Overview
135
+ #### 2. Project Overview
154
136
 
155
137
  | Item | Value |
156
138
  |---|---|
@@ -166,12 +148,12 @@ an XML-driven MyBatis persistence layer and JWT-based authentication.
166
148
  | Test Stack | JUnit Jupiter 5, Mockito, AssertJ, rest-assured, spring-mock-mvc |
167
149
  ```
168
150
 
169
- Mọi giá trị bên trên — tọa độ dependency chính xác, tên tệp `dev.db`, tên migration `V1__create_tables.sql`, "no JPA" — đều được scanner trích xuất từ `build.gradle` / `application.properties` / cây mã nguồn trước khi Claude viết tệp. Không có gì là phỏng đoán.
151
+ Mọi giá trị trong bảng trên đều do scanner đọc thẳng từ `build.gradle`, `application.properties` và cây source trước khi Claude viết file. Toạ độ dependency, tên file `dev.db`, tên migration `V1__create_tables.sql`, ghi chú "no JPA" — tất cả đều là sự thật trích xuất, không chỗ nào là phỏng đoán.
170
152
 
171
153
  </details>
172
154
 
173
155
  <details>
174
- <summary><strong>🛡️ Một rule thật được tự động nạp (<code>.claude/rules/10.backend/01.controller-rules.md</code>)</strong></summary>
156
+ <summary><strong>Một rule auto-load thật (<code>.claude/rules/10.backend/01.controller-rules.md</code>)</strong></summary>
175
157
 
176
158
  ````markdown
177
159
  ---
@@ -179,9 +161,9 @@ paths:
179
161
  - "**/*"
180
162
  ---
181
163
 
182
- # Controller Rules
164
+ #### Controller Rules
183
165
 
184
- ## REST (`io.spring.api.*`)
166
+ ##### REST (`io.spring.api.*`)
185
167
 
186
168
  - Controllers are the SOLE response wrapper for HTTP — no aggregator/facade above them.
187
169
  Return `ResponseEntity<?>` or a body Spring serializes via `JacksonCustomizations`.
@@ -194,13 +176,13 @@ paths:
194
176
  - Let exceptions propagate to `io.spring.api.exception.CustomizeExceptionHandler`
195
177
  (`@ControllerAdvice`). Do NOT `try/catch` business exceptions inside the controller.
196
178
 
197
- ## GraphQL (`io.spring.graphql.*`)
179
+ ##### GraphQL (`io.spring.graphql.*`)
198
180
 
199
181
  - DGS components (`@DgsComponent`) are the sole GraphQL response wrappers.
200
182
  Use `@DgsQuery` / `@DgsData` / `@DgsMutation`.
201
183
  - Resolve the current user via `io.spring.graphql.SecurityUtil.getCurrentUser()`.
202
184
 
203
- ## Examples
185
+ ##### Examples
204
186
 
205
187
  ✅ Correct:
206
188
  ```java
@@ -228,15 +210,15 @@ public ResponseEntity<?> create(@RequestBody NewArticleParam p) {
228
210
  ```
229
211
  ````
230
212
 
231
- Glob `paths: ["**/*"]` có nghĩa là Claude Code tự động nạp rule này mỗi khi bạn chỉnh bất kỳ tệp nào trong dự án. Mọi tên class, đường dẫn package, exception handler trong rule đều được lấy thẳng từ source đã scan — bao gồm cả `CustomizeExceptionHandler` và `JacksonCustomizations` thực tế của dự án.
213
+ Glob `paths: ["**/*"]` nghĩa là Claude Code sẽ tự động nạp rule này mỗi khi sửa bất kỳ file nào trong dự án. Tên class, đường dẫn package, exception handler trong rule đều lấy nguyên văn từ source đã quét, kể cả `CustomizeExceptionHandler` và `JacksonCustomizations` thật của dự án.
232
214
 
233
215
  </details>
234
216
 
235
217
  <details>
236
- <summary><strong>🧠 Hạt mầm <code>decision-log.md</code> tự sinh (trích đoạn thực tế)</strong></summary>
218
+ <summary><strong>Một seed <code>decision-log.md</code> được sinh tự động (trích đoạn thật)</strong></summary>
237
219
 
238
220
  ```markdown
239
- ## 2026-04-26 — Hexagonal ports & adapters with MyBatis-only persistence
221
+ #### 2026-04-26 — Hexagonal ports & adapters with MyBatis-only persistence
240
222
 
241
223
  - **Context:** `io.spring.core.*` exposes `*Repository` ports (e.g.,
242
224
  `io.spring.core.article.ArticleRepository`) implemented by
@@ -255,260 +237,276 @@ Glob `paths: ["**/*"]` có nghĩa là Claude Code tự động nạp rule này m
255
237
  split the persistence model.
256
238
  ```
257
239
 
258
- Pass 4 gieo `decision-log.md` bằng các quyết định kiến trúc được trích từ `pass2-merged.json`, để các phiên sau ghi nhớ *vì sao* codebase trông như vậy — không chỉ *trông như thế nào*. Mọi tùy chọn ("JPA/Hibernate", "MyBatis-Plus") và mọi hệ quả đều bắt nguồn từ chính khối dependency `build.gradle` thực tế.
240
+ Pass 4 ghi sẵn các quyết định kiến trúc trích từ `pass2-merged.json` vào `decision-log.md`. Nhờ vậy, các phiên về sau không chỉ biết codebase _trông như thế nào_, mà còn nhớ được _vì sao nó lại như vậy_. Mọi option ("JPA/Hibernate", "MyBatis-Plus") cùng các consequence đều neo vào block dependency có thật trong `build.gradle`.
259
241
 
260
242
  </details>
261
243
 
262
244
  ---
263
245
 
264
- ## Quick Start
246
+ ## Đã kiểm thử trên
247
+
248
+ ClaudeOS-Core đi kèm các benchmark tham chiếu trên dự án OSS thật. Nếu đã thử trên một public repo nào đó, hãy [mở issue](https://github.com/claudeos-core/claudeos-core/issues) để chúng tôi bổ sung vào bảng này.
265
249
 
266
- **Yêu cầu trước:** Node.js 18+, [Claude Code](https://docs.anthropic.com/en/docs/claude-code) đã cài đặt và xác thực.
250
+ | Dự án | Stack | Scanned → Generated | Trạng thái |
251
+ |---|---|---|---|
252
+ | [`spring-boot-realworld-example-app`](https://github.com/gothinkster/spring-boot-realworld-example-app) | Java 11 · Spring Boot 2.6 · MyBatis · SQLite | 187 → 75 files | ✅ cả 5 validator đều pass |
253
+
254
+ ---
255
+
256
+ ## Bắt đầu nhanh
257
+
258
+ **Yêu cầu trước:** Node.js 18 trở lên, [Claude Code](https://docs.anthropic.com/en/docs/claude-code) đã cài và đã đăng nhập.
267
259
 
268
260
  ```bash
269
- # 1. Vào thư mục gốc dự án
261
+ # 1. Vào thư mục gốc của dự án
270
262
  cd my-spring-boot-project
271
263
 
272
- # 2. Chạy init (lệnh này phân tích code và yêu cầu Claude viết rules)
264
+ # 2. Chạy init (lệnh này quét code rồi nhờ Claude viết rules)
273
265
  npx claudeos-core init
274
266
 
275
- # 3. Xong. Mở Claude Code và bắt đầu code — rules đã được nạp sẵn.
267
+ # 3. Xong. Mở Claude Code và bắt tay vào code — rules đã sẵn sàng.
276
268
  ```
277
269
 
278
- **Bạn sẽ có** sau khi `init` hoàn tất:
270
+ Sau khi `init` hoàn tất, bạn sẽ thấy cấu trúc như sau.
279
271
 
280
272
  ```
281
273
  your-project/
282
274
  ├── .claude/
283
- │ └── rules/ ← Tự động nạp bởi Claude Code
275
+ │ └── rules/ ← Claude Code tự động load
284
276
  │ ├── 00.core/ (rules chung — naming, kiến trúc)
285
277
  │ ├── 10.backend/ (rules backend stack, nếu có)
286
278
  │ ├── 20.frontend/ (rules frontend stack, nếu có)
287
- │ ├── 30.security-db/ (quy ước bảo mật & DB)
279
+ │ ├── 30.security-db/ (quy ước bảo mật và DB)
288
280
  │ ├── 40.infra/ (env, logging, CI/CD)
289
- │ ├── 50.sync/ (nhắc đồng bộ doc — chỉ rules)
281
+ │ ├── 50.sync/ (nhắc đồng bộ tài liệu — chỉ rules)
290
282
  │ ├── 60.memory/ (memory rules — Pass 4, chỉ rules)
291
283
  │ ├── 70.domains/{type}/ (rules theo domain, type = backend|frontend)
292
- │ └── 80.verification/ (chiến lược test + nhắc xác minh build)
284
+ │ └── 80.verification/ (chiến lược test và nhắc verify build)
293
285
  ├── claudeos-core/
294
- │ ├── standard/ ← Tài liệu tham chiếu (mirror cấu trúc category)
295
- │ │ ├── 00.core/ (project overview, kiến trúc, naming)
296
- │ │ ├── 10.backend/ (reference backend — nếu có backend stack)
297
- │ │ ├── 20.frontend/ (reference frontend — nếu có frontend stack)
298
- │ │ ├── 30.security-db/ (reference bảo mật & DB)
299
- │ │ ├── 40.infra/ (reference env / logging / CI-CD)
300
- │ │ ├── 70.domains/{type}/ (reference theo domain)
301
- │ │ ├── 80.verification/ (reference build / startup / testing — chỉ standard)
302
- │ │ └── 90.optional/ (mở rộng riêng cho stack — chỉ standard)
303
- │ ├── skills/ (mẫu tái sử dụng mà Claude có thể áp dụng)
304
- │ ├── guide/ (hướng dẫn how-to cho các tác vụ thường gặp)
286
+ │ ├── standard/ ← Tài liệu tham chiếu (cấu trúc category song song)
287
+ │ │ ├── 00.core/ (tổng quan dự án, kiến trúc, naming)
288
+ │ │ ├── 10.backend/ (tham chiếu backend — nếu có backend stack)
289
+ │ │ ├── 20.frontend/ (tham chiếu frontend — nếu có frontend stack)
290
+ │ │ ├── 30.security-db/ (tham chiếu bảo mật và DB)
291
+ │ │ ├── 40.infra/ (tham chiếu env / logging / CI-CD)
292
+ │ │ ├── 70.domains/{type}/ (tham chiếu theo domain)
293
+ │ │ ├── 80.verification/ (tham chiếu build / startup / test — chỉ standard)
294
+ │ │ └── 90.optional/ (mở rộng theo stack — chỉ standard)
295
+ │ ├── skills/ (pattern tái sử dụng để Claude áp dụng)
296
+ │ ├── guide/ (hướng dẫn how-to cho các tác vụ phổ biến)
305
297
  │ ├── database/ (tổng quan schema, hướng dẫn migration)
306
298
  │ ├── mcp-guide/ (ghi chú tích hợp MCP)
307
299
  │ └── memory/ (decision log, failure patterns, compaction)
308
- └── CLAUDE.md (chỉ mục Claude đọc đầu tiên)
300
+ └── CLAUDE.md (index Claude đọc đầu tiên)
309
301
  ```
310
302
 
311
- Các category dùng chung tiền tố số giữa `rules/` và `standard/` đại diện cho cùng một mảng khái niệm (ví dụ: `10.backend` rules ↔ `10.backend` standards). Category chỉ-rules: `50.sync` (nhắc đồng bộ doc) và `60.memory` (Pass 4 memory). Category chỉ-standard: `90.optional` (mở rộng riêng stack, không cưỡng chế). Mọi tiền tố khác (`00`, `10`, `20`, `30`, `40`, `70`, `80`) xuất hiện ở CẢ `rules/` và `standard/`. Giờ Claude Code đã hiểu dự án của bạn.
303
+ Các category cùng số prefix ở `rules/` và `standard/` cùng chỉ về một vùng khái niệm. Chẳng hạn `10.backend` rules đối ứng `10.backend` standards. Hai category chỉ tồn tại bên rules là `50.sync` (nhắc đồng bộ tài liệu) và `60.memory` (memory của Pass 4). Phía standard có một category riêng là `90.optional`, dành cho phần mở rộng theo stack và không enforce. Các prefix còn lại (`00`, `10`, `20`, `30`, `40`, `70`, `80`) thì xuất hiện ở cả hai bên. Đến đây, Claude Code đã hiểu dự án của bạn.
312
304
 
313
305
  ---
314
306
 
315
307
  ## Dành cho ai?
316
308
 
317
- | Bạn là... | Pain mà công cụ này gỡ bỏ |
309
+ | Bạn là... | Vấn đề được giải quyết |
318
310
  |---|---|
319
- | **Dev solo** đang khởi tạo dự án mới với Claude Code | "Dạy Claude quy ước của tôi mỗi phiên" — biến mất. `CLAUDE.md` + `.claude/rules/` 8-category được sinh trong một lần chạy. |
320
- | **Team lead** duy trì chuẩn dùng chung qua nhiều repo | `.claude/rules/` drift khi mọi người đổi tên package, đổi ORM, đổi response wrapper. ClaudeOS-Core đồng bộ lại deterministic — cùng đầu vào, đầu ra byte-identical, không có diff noise. |
321
- | **Đã dùng Claude Code** nhưng mệt mỏi vì sửa code được sinh | Sai response wrapper, sai layout package, JPA khi bạn dùng MyBatis, `try/catch` rải khắp khi dự án bạn dùng centralized middleware. Scanner trích các quy ước thật của bạn; mỗi pass Claude chạy dựa trên một path allowlist tường minh. |
322
- | **Onboarding một repo mới** (dự án sẵn có, gia nhập đội mới) | Chạy `init` trên repo, nhận một bản đồ kiến trúc sống: bảng stack trong CLAUDE.md, rules từng layer kèm ví dụ ✅/❌, decision log đã gieo "vì sao" sau các lựa chọn lớn (JPA vs MyBatis, REST vs GraphQL, v.v.). Đọc 5 tệp thắng đọc 5.000 source file. |
323
- | **Làm việc bằng tiếng Hàn / Nhật / Trung / 7 ngôn ngữ khác** | Hầu hết các bộ sinh rule Claude Code chỉ hỗ trợ tiếng Anh. ClaudeOS-Core viết toàn bộ bằng **10 ngôn ngữ** (`en/ko/ja/zh-CN/es/vi/hi/ru/fr/de`) với **xác minh cấu trúc byte-identical** — cùng verdict `claude-md-validator` bất kể ngôn ngữ đầu ra. |
324
- | **Đang chạy trên monorepo** (Turborepo, pnpm/yarn workspaces, Lerna) | Domain backend + frontend được phân tích trong một lần chạy với prompt riêng biệt; `apps/*/` và `packages/*/` được walk tự động; rules theo từng stack được emit dưới `70.domains/{type}/`. |
325
- | **Đóng góp OSS hoặc thử nghiệm** | Đầu ra thân thiện với gitignore — `claudeos-core/` là thư mục làm việc local của bạn, chỉ `CLAUDE.md` + `.claude/` cần ship. Resume-safe khi bị gián đoạn; idempotent khi chạy lại (chỉnh sửa thủ công của bạn được giữ lại nếu không có `--force`). |
311
+ | **Solo dev** đang khởi động dự án mới với Claude Code | Khỏi phải dạy lại quy ước cho Claude mỗi phiên. `CLAUDE.md` cùng 8 category trong `.claude/rules/` được sinh ra chỉ trong một lần chạy. |
312
+ | **Team lead** quản lý standards dùng chung giữa nhiều repo | `.claude/rules/` rất hay drift mỗi khi đổi tên package, đổi ORM hay đổi response wrapper. ClaudeOS-Core đồng bộ lại một cách nhất quán: cùng input thì ra output byte-identical, không có diff thừa. |
313
+ | **Đã quen Claude Code** nhưng chán cảnh phải sửa lại code mỗi lần | Sai response wrapper, sai cấu trúc package, viết JPA trong khi dự án dùng MyBatis, rải `try/catch` trong khi đã có middleware tập trung. Scanner trích quy ước thật của dự án, mỗi pass của Claude đều chạy trong allowlist tường minh. |
314
+ | **Onboard vào repo mới** (dự án có sẵn, vào team mới) | Chạy `init` xong là có ngay tấm bản đồ kiến trúc sống. Bảng stack trong CLAUDE.md, rules theo từng layer kèm ví dụ ✅/❌, decision log seed sẵn lý do đằng sau những lựa chọn lớn (JPA hay MyBatis, REST hay GraphQL...). Đọc 5 file vẫn nhanh hơn lội qua 5.000 file source. |
315
+ | **Làm việc bằng tiếng Hàn, Nhật, Trung và 7 ngôn ngữ khác** | Phần lớn rule generator cho Claude Code chỉ có tiếng Anh. ClaudeOS-Core viết toàn bộ ở **10 ngôn ngữ** (`en/ko/ja/zh-CN/es/vi/hi/ru/fr/de`) và áp **kiểm tra cấu trúc byte-identical**. Verdict của `claude-md-validator` không đổi dù chọn ngôn ngữ output nào. |
316
+ | **Đang dùng monorepo** (Turborepo, pnpm/yarn workspaces, Lerna) | Domain backend và frontend được phân tích trong cùng một lần chạy nhưng bằng prompt riêng. `apps/*/` và `packages/*/` được duyệt tự động, rules theo từng stack đổ vào `70.domains/{type}/`. |
317
+ | **Đóng góp OSS hoặc đang thử nghiệm** | Output thân thiện với gitignore. `claudeos-core/` là thư mục làm việc local, chỉ `CLAUDE.md` và `.claude/` cần ship. Đứt giữa chừng vẫn tiếp tục được, chạy lại nhiều lần vẫn an toàn (chỉnh sửa tay không bị mất nếu không kèm `--force`). |
326
318
 
327
- **Không phù hợp nếu:** bạn muốn một bundle preset agents/skills/rules dạng one-size-fits-all chạy được ngay từ ngày đầu mà không cần bước scan (xem [docs/vi/comparison.md](docs/vi/comparison.md) để biết công cụ nào hợp với việc gì), dự án của bạn chưa khớp với một trong các [stack được hỗ trợ](#supported-stacks), hoặc bạn chỉ cần một `CLAUDE.md` đơn giản (built-in `claude /init` là đủ — không cần cài thêm công cụ).
319
+ **Có thể không phù hợp nếu** bạn muốn một bundle preset agents/skills/rules xài được ngay từ ngày đầu mà không cần bước scan (xem [docs/vi/comparison.md](docs/vi/comparison.md) để biết công cụ nào hợp với hoàn cảnh nào), dự án chưa rơi vào một trong các [stack được hỗ trợ](#supported-stacks), hoặc chỉ cần đúng một file `CLAUDE.md`. Riêng trường hợp cuối thì `claude /init` có sẵn là đủ, khỏi cài thêm tool nào khác.
328
320
 
329
321
  ---
330
322
 
331
- ## Hoạt động thế nào?
323
+ ## Cách hoạt động
332
324
 
333
- ClaudeOS-Core đảo ngược workflow Claude Code thông thường:
325
+ ClaudeOS-Core đảo ngược workflow Claude Code thông thường.
334
326
 
335
327
  ```
336
- Thông thường: Bạn mô tả dự án → Claude đoán stack → Claude viết doc
337
- Công cụ này: Code đọc stack → Code đưa sự kiện đã xác nhận cho Claude → Claude viết doc từ sự kiện
328
+ Thông thường: Bạn mô tả dự án → Claude đoán stack của bạn → Claude viết docs
329
+ Cách này: Code đọc stack của bạn → Code đưa fact đã xác nhận cho Claude → Claude viết docs từ fact
338
330
  ```
339
331
 
340
- Pipeline chạy theo **3 giai đoạn**, với code ở cả hai phía của lời gọi LLM:
332
+ Pipeline gồm **ba giai đoạn**, code có mặt ở cả hai phía của lời gọi LLM.
341
333
 
342
- **1. Step A — Scanner (deterministic, không LLM).** Một Node.js scanner walk qua thư mục gốc dự án, đọc `package.json` / `build.gradle` / `pom.xml` / `pyproject.toml`, parse các tệp `.env*` (với redaction biến nhạy cảm cho `PASSWORD/SECRET/TOKEN/JWT_SECRET/...`), phân loại pattern kiến trúc (5 pattern A/B/C/D/E của Java, Kotlin CQRS / multi-module, Next.js App vs Pages Router, FSD, components-pattern), khám phá các domain, và xây dựng allowlist tường minh cho mọi đường dẫn source tồn tại. Đầu ra: `project-analysis.json` — single source of truth cho mọi bước sau.
334
+ **1. Step A — Scanner (nhất quán, không gọi LLM).** Một Node.js scanner đi qua thư mục gốc, đọc `package.json`, `build.gradle`, `pom.xml`, `pyproject.toml`, parse các file `.env*` (đồng thời redact các biến nhạy cảm như `PASSWORD/SECRET/TOKEN/JWT_SECRET/...`), phân loại pattern kiến trúc (5 pattern A/B/C/D/E của Java; Kotlin CQRS hoặc multi-module; Next.js App Router so với Pages Router; FSD; components-pattern), tìm ra các domain, rồi dựng allowlist tường minh chứa mọi đường dẫn source thật. Output là `project-analysis.json`, đóng vai trò single source of truth cho mọi bước về sau.
343
335
 
344
- **2. Step B — Pipeline Claude 4-pass (bị ràng buộc bởi sự kiện của Step A).**
345
- - **Pass 1** đọc các tệp đại diện theo nhóm domain và trích ~50–100 quy ước mỗi domain — response wrapper, thư viện logging, error handling, quy ước đặt tên, pattern test. Chạy một lần mỗi nhóm domain (`max 4 domains, 40 files per group`) nên context không bao giờ overflow.
346
- - **Pass 2** gộp toàn bộ phân tích theo từng domain thành bức tranh toàn dự án và giải quyết bất đồng bằng cách chọn quy ước trội nhất.
347
- - **Pass 3** viết `CLAUDE.md` + `.claude/rules/` + `claudeos-core/standard/` + skills + guides — split thành các stage (`3a` facts → `3b-core/3b-N` rules+standards → `3c-core/3c-N` skills+guides → `3d-aux` database+mcp-guide) để prompt mỗi stage vừa với context window của LLM kể cả khi `pass2-merged.json` lớn. Sub-divide 3b/3c thành các batch ≤15 domain cho dự án ≥16 domain.
348
- - **Pass 4** gieo lớp L4 memory (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`) và thêm các universal scaffold rule. Pass 4 **bị cấm chỉnh sửa `CLAUDE.md`** — Section 8 của Pass 3 là authoritative.
336
+ **2. Step B — Pipeline Claude 4-pass (ràng buộc bởi fact của Step A).**
337
+ - **Pass 1** đọc các file đại diện theo từng domain group rồi trích ra khoảng 50–100 quy ước cho mỗi domain: response wrapper, thư viện logging, cách xử lý lỗi, quy ước naming, pattern test. Mỗi domain group chỉ chạy một lần (`max 4 domains, 40 files per group`) nên context không bao giờ tràn.
338
+ - **Pass 2** gộp toàn bộ phân tích theo domain thành bức tranh chung của dự án. Có mâu thuẫn thì công cụ chọn quy ước phổ biến nhất.
339
+ - **Pass 3** viết `CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, skills và guides. Bước này được chia thành nhiều stage (`3a` facts → `3b-core/3b-N` rules+standards → `3c-core/3c-N` skills+guides → `3d-aux` database+mcp-guide) để prompt mỗi stage vẫn vừa context window dù `pass2-merged.json` có lớn cỡ nào. Với dự án từ 16 domain trở lên, 3b/3c sẽ chia tiếp thành các batch ≤15 domain.
340
+ - **Pass 4** seed L4 memory layer (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`) và bổ sung các rule scaffold phổ quát. Pass 4 **tuyệt đối không được sửa `CLAUDE.md`**. Section 8 do Pass 3 viết mới là nguồn duy nhất.
349
341
 
350
- **3. Step C — Verification (deterministic, không LLM).** Năm validator kiểm tra đầu ra:
351
- - `claude-md-validator` — 25 kiểm tra cấu trúc trên `CLAUDE.md` (8 sections, đếm H3/H4, tính duy nhất của memory file, T1 canonical heading invariant). Language-invariant: cùng verdict bất kể `--lang`.
352
- - `content-validator` — 10 kiểm tra nội dung gồm xác minh path-claim (`STALE_PATH` bắt các tham chiếu `src/...` bị bịa) và phát hiện MANIFEST drift.
353
- - `pass-json-validator` — Pass 1/2/3/4 well-formed JSON + đếm section theo stack.
354
- - `plan-validator` — nhất quán plan ↔ disk (legacy, gần như no-op từ v2.1.0).
355
- - `sync-checker` — nhất quán đăng ký disk ↔ `sync-map.json` qua 7 thư mục được theo dõi.
342
+ **3. Step C — Verification (nhất quán, không gọi LLM).** Năm validator soi lại kết quả.
343
+ - `claude-md-validator` chạy 25 kiểm tra cấu trúc trên `CLAUDE.md` (8 section, đếm H3/H4, tính duy nhất của file memory, bất biến T1 canonical heading). Validator này language-invariant, nên chọn `--lang` nào cũng ra cùng verdict.
344
+ - `content-validator` chạy 10 kiểm tra nội dung, gồm verify path-claim (`STALE_PATH` bắt được tham chiếu `src/...` bịa đặt) và phát hiện MANIFEST drift.
345
+ - `pass-json-validator` kiểm tra JSON well-formedness của Pass 1/2/3/4 cùng số section theo từng stack.
346
+ - `plan-validator` so plan với disk (legacy, gần như no-op từ v2.1.0).
347
+ - `sync-checker` đối chiếu disk với `sync-map.json` qua 7 thư mục được track.
356
348
 
357
- Ba mức severity (`fail` / `warn` / `advisory`) để warning không bao giờ deadlock CI vì hallucination LLM mà người dùng có thể tự sửa.
349
+ Có ba mức severity (`fail` / `warn` / `advisory`), nhờ vậy các warning kiểu hallucination LLM mà dev tự sửa được sẽ không bao giờ làm kẹt CI.
358
350
 
359
- Bất biến gắn kết tất cả: **Claude chỉ có thể trích các đường dẫn thật sự tồn tại trong code của bạn**, vì Step A trao cho nó một allowlist hữu hạn. Nếu LLM vẫn cố bịa (hiếm nhưng xảy ra với vài seed), Step C bắt được trước khi docs ship.
351
+ Cốt lõi gắn kết tất cả lại là một bất biến: **Claude chỉ được trích dẫn các đường dẫn có thật trong code**, vì Step A đã đưa cho nó một allowlist hữu hạn. Tuy nhiên, nếu LLM vẫn cố bịa (hiếm gặp, chỉ xuất hiện ở vài seed cụ thể) thì Step C cũng sẽ bắt lại trước khi docs được ship.
360
352
 
361
- Chi tiết per-pass, resume dựa trên marker, workaround staged-rules cho `.claude/` sensitive-path block của Claude Code, và internals của stack detection xem [docs/vi/architecture.md](docs/vi/architecture.md).
353
+ Để xem chi tiết từng pass, cơ chế resume dựa trên marker, workaround staged-rules dùng để vượt qua block đường dẫn nhạy cảm `.claude/` của Claude Code, cùng internals của stack detection, mời đọc [docs/vi/architecture.md](docs/vi/architecture.md).
362
354
 
363
355
  ---
364
356
 
365
357
  ## Supported Stacks
366
358
 
367
- 12 stack, tự động phát hiện từ tệp dự án:
359
+ 12 stack, tự động phát hiện từ chính các file dự án.
368
360
 
369
361
  **Backend:** Java/Spring Boot · Kotlin/Spring Boot · Node/Express · Node/Fastify · Node/NestJS · Python/Django · Python/FastAPI · Python/Flask
370
362
 
371
363
  **Frontend:** Node/Next.js · Node/Vite · Angular · Vue/Nuxt
372
364
 
373
- Dự án đa-stack (ví dụ: Spring Boot backend + Next.js frontend) hoạt động ngay không cần cấu hình.
365
+ Dự án multi-stack (chẳng hạn Spring Boot backend cộng Next.js frontend) chạy được luôn mà không cần điều chỉnh.
374
366
 
375
- Quy tắc phát hiện và những gì mỗi scanner trích xuất xem tại [docs/vi/stacks.md](docs/vi/stacks.md).
367
+ Quy tắc phát hiện và những gì mỗi scanner trích xuất được mô tả trong [docs/vi/stacks.md](docs/vi/stacks.md).
376
368
 
377
369
  ---
378
370
 
379
- ## Workflow hằng ngày
371
+ ## Quy trình hàng ngày
380
372
 
381
- Ba lệnh phủ ~95% nhu cầu sử dụng:
373
+ Ba lệnh sau đủ dùng cho khoảng 95% trường hợp.
382
374
 
383
375
  ```bash
384
- # Lần đầu trên một dự án
376
+ # Lần đầu chạy trên một dự án
385
377
  npx claudeos-core init
386
378
 
387
- # Sau khi bạn chỉnh thủ công standards hoặc rules
379
+ # Sau khi bạn chỉnh tay standards hoặc rules
388
380
  npx claudeos-core lint
389
381
 
390
- # Health check (chạy trước khi commit, hoặc trong CI)
382
+ # Health check (chạy trước khi commit hoặc trong CI)
391
383
  npx claudeos-core health
392
384
  ```
393
385
 
394
- Hai lệnh nữa cho bảo trì memory layer:
395
-
396
- ```bash
397
- # Compact log failure-patterns (chạy định kỳ)
398
- npx claudeos-core memory compact
399
-
400
- # Đề xuất các pattern lỗi thường gặp thành rule mới
401
- npx claudeos-core memory propose-rules
402
- ```
403
-
404
- Tùy chọn đầy đủ của từng lệnh xem tại [docs/vi/commands.md](docs/vi/commands.md).
386
+ Đầy đủ option của từng lệnh có trong [docs/vi/commands.md](docs/vi/commands.md). Các lệnh thuộc memory layer (`memory compact`, `memory propose-rules`) được nói rõ ở phần [Memory Layer](#memory-layer-tùy-chọn-cho-dự-án-dài-hạn) bên dưới.
405
387
 
406
388
  ---
407
389
 
408
- ## Điều gì làm công cụ này khác biệt
390
+ ## Điểm khác biệt
409
391
 
410
- Hầu hết công cụ sinh tài liệu Claude Code đều sinh từ một mô tả (bạn nói cho công cụ, công cụ nói cho Claude). ClaudeOS-Core sinh từ chính mã nguồn của bạn (công cụ đọc, công cụ nói cho Claude phần nào đã được xác nhận, Claude chỉ viết những gì đã được xác nhận).
392
+ Phần lớn công cụ tài liệu cho Claude Code sinh ra từ một bản mô tả: bạn nói cho công cụ, công cụ nói lại cho Claude. ClaudeOS-Core thì sinh thẳng từ source code thật. Công cụ tự đọc, tự đẩy các fact đã xác nhận sang Claude, còn Claude chỉ viết đúng những gì đã được xác nhận.
411
393
 
412
- Ba hệ quả cụ thể:
394
+ Cách làm này dẫn tới ba điểm khác biệt cụ thể.
413
395
 
414
- 1. **Phát hiện stack có tính deterministic.** Cùng dự án + cùng code = cùng đầu ra. Không có chuyện "lần này Claude đoán khác."
415
- 2. **Không bịa ra đường dẫn.** Prompt của Pass 3 liệt kê tường minh mọi đường dẫn nguồn được phép; Claude không thể trích các đường dẫn không tồn tại.
416
- 3. **Hiểu đa-stack.** Domain backend và frontend dùng prompt phân tích khác nhau trong cùng một lần chạy.
396
+ 1. **Stack detection nhất quán.** Cùng dự án, cùng code thì luôn ra cùng output. Hết cảnh "lần này Claude lại đoán khác".
397
+ 2. **Không tạo path bịa.** Prompt của Pass 3 liệt kê tường minh mọi source path được phép, vì thế Claude không thể trích ra path không tồn tại.
398
+ 3. **Hiểu được multi-stack.** Trong cùng một lần chạy, domain backend và frontend dùng prompt phân tích riêng.
417
399
 
418
- So sánh phạm vi side-by-side với các công cụ khác xem [docs/vi/comparison.md](docs/vi/comparison.md). So sánh là về **mỗi công cụ làm gì**, không phải **cái nào tốt hơn** — phần lớn là bổ trợ nhau.
400
+ Muốn so sánh scope cạnh nhau với các công cụ khác, mời đọc [docs/vi/comparison.md](docs/vi/comparison.md). Nội dung tập trung vào **mỗi công cụ làm gì**, chứ không phải **công cụ nào tốt hơn**. Thực ra phần lớn là bổ sung cho nhau.
419
401
 
420
402
  ---
421
403
 
422
- ## Xác minh (sau khi sinh)
404
+ ## Xác minh (sau khi tạo)
423
405
 
424
- Sau khi Claude viết doc, code sẽ xác minh chúng. Năm validator độc lập:
406
+ Sau khi Claude viết xong docs, đến lượt code kiểm tra lại. Năm validator độc lập như sau.
425
407
 
426
- | Validator | Kiểm tra gì | Chạy bởi |
408
+ | Validator | Kiểm tra cái gì | Chạy bởi |
427
409
  |---|---|---|
428
- | `claude-md-validator` | Bất biến cấu trúc của CLAUDE.md (8 sections, language-invariant) | `claudeos-core lint` |
429
- | `content-validator` | Đường dẫn nêu trong tài liệu thật sự tồn tại; manifest nhất quán | `health` (advisory) |
430
- | `pass-json-validator` | Đầu ra Pass 1 / 2 / 3 / 4 là JSON đúng cú pháp | `health` (warn) |
431
- | `plan-validator` | Plan đã lưu khớp với đĩa | `health` (fail-on-error) |
432
- | `sync-checker` | Tệp trên đĩa khớp với đăng ký trong `sync-map.json` (phát hiện orphaned/unregistered) | `health` (fail-on-error) |
410
+ | `claude-md-validator` | Bất biến cấu trúc của CLAUDE.md (8 section, language-invariant) | `claudeos-core lint` |
411
+ | `content-validator` | Path claim có thật trong code; manifest nhất quán | `health` (advisory) |
412
+ | `pass-json-validator` | Output Pass 1 / 2 / 3 / 4 là JSON hợp lệ | `health` (warn) |
413
+ | `plan-validator` | Plan đã lưu khớp với disk | `health` (fail-on-error) |
414
+ | `sync-checker` | File trên disk khớp với đăng ký trong `sync-map.json` (phát hiện orphaned/unregistered) | `health` (fail-on-error) |
433
415
 
434
- Một `health-checker` điều phối bốn validator runtime với mức độ ba bậc (fail / warn / advisory) và thoát với exit code phù hợp cho CI. `claude-md-validator` chạy riêng qua lệnh `lint` vì lệch cấu trúc là tín hiệu cần re-init, không phải warning nhẹ. Có thể chạy bất cứ lúc nào:
416
+ `health-checker` điều phối bốn runtime validator theo ba mức severity (fail / warn / advisory) và thoát với mã phù hợp cho CI. Riêng `claude-md-validator` chạy độc lập qua lệnh `lint`, vì cấu trúc bị drift là tín hiệu cần re-init, không phải warning mềm. Có thể chạy bất kỳ lúc nào.
435
417
 
436
418
  ```bash
437
419
  npx claudeos-core health
438
420
  ```
439
421
 
440
- Chi tiết kiểm tra của từng validator xem [docs/vi/verification.md](docs/vi/verification.md).
422
+ Chi tiết kiểm tra của từng validator có trong [docs/vi/verification.md](docs/vi/verification.md).
441
423
 
442
424
  ---
443
425
 
444
- ## Memory Layer (tùy chọn, dành cho dự án dài hạn)
426
+ ## Memory Layer (tùy chọn, cho dự án dài hạn)
445
427
 
446
- Sau v2.0, ClaudeOS-Core ghi một thư mục `claudeos-core/memory/` chứa bốn tệp:
428
+ Ngoài pipeline scaffolding kể trên, ClaudeOS-Core còn seed thêm thư mục `claudeos-core/memory/` cho những dự án cần giữ context vượt ra ngoài một phiên đơn lẻ. Phần này là tùy chọn. Nếu chỉ cần `CLAUDE.md` và rules thì cứ bỏ qua, không sao cả.
447
429
 
448
- - `decision-log.md` — append-only "vì sao chọn X thay vì Y"
449
- - `failure-patterns.md` — lỗi tái diễn kèm điểm frequency/importance
430
+ Bốn file, tất cả đều do Pass 4 viết.
431
+
432
+ - `decision-log.md` — sổ append-only ghi "vì sao chọn X thay vì Y", seed từ `pass2-merged.json`
433
+ - `failure-patterns.md` — danh sách lỗi lặp lại kèm điểm frequency và importance
450
434
  - `compaction.md` — cách memory được tự động compact theo thời gian
451
- - `auto-rule-update.md` — pattern cần được biến thành rule mới
435
+ - `auto-rule-update.md` — các pattern nên được nâng thành rule mới
436
+
437
+ Hai lệnh để duy trì layer này lâu dài.
438
+
439
+ ```bash
440
+ # Compact log failure-patterns (chạy định kỳ)
441
+ npx claudeos-core memory compact
452
442
 
453
- Bạn có thể chạy `npx claudeos-core memory propose-rules` để yêu cầu Claude xem xét các pattern lỗi gần đây và đề xuất rule mới.
443
+ # Đề xuất rule mới từ các failure pattern xuất hiện thường xuyên
444
+ npx claudeos-core memory propose-rules
445
+ ```
454
446
 
455
- Mô hình memory và vòng đời xem [docs/vi/memory-layer.md](docs/vi/memory-layer.md).
447
+ Mô hình memory và lifecycle được mô tả trong [docs/vi/memory-layer.md](docs/vi/memory-layer.md).
456
448
 
457
449
  ---
458
450
 
459
451
  ## FAQ
460
452
 
461
- **H: Tôi có cần Claude API key không?**
462
- Đ: Không. ClaudeOS-Core dùng cài đặt Claude Code sẵn có của bạn — nó truyền prompt đến `claude -p` trên máy bạn. Không cần tài khoản phụ.
453
+ **Q: Có cần Claude API key không?**
454
+ A: Không. ClaudeOS-Core dùng chính bản Claude Code đã cài trên máy. Prompt được pipe sang `claude -p` ngay tại máy, khỏi cần thêm tài khoản nào khác.
463
455
 
464
- **H: Lệnh này có ghi đè CLAUDE.md hoặc `.claude/rules/` đang có không?**
465
- Đ: Lần chạy đầu trên dự án mới: tạo mới. Chạy lại không có `--force` thì giữ nguyên chỉnh sửa của bạn — marker từ lần chạy trước được phát hiện và pass đó bị bỏ qua. Chạy lại với `--force` thì xóa và sinh lại tất cả (các chỉnh sửa của bạn bị mất — đó chính là ý nghĩa của `--force`). Xem [docs/vi/safety.md](docs/vi/safety.md).
456
+ **Q: Lệnh này có ghi đè `CLAUDE.md` hay `.claude/rules/` đang có không?**
457
+ A: Lần đầu chạy trên dự án trống thì nó tạo mới. Chạy lại không kèm `--force` thì các chỉnh sửa tay được giữ nguyên, vì marker từ lần chạy trước được phát hiện và pass tương ứng sẽ bị skip. Còn nếu kèm `--force` thì mọi thứ sẽ bị xóa rồi sinh lại, kéo theo phần chỉnh sửa cũng mất. Đó đúng là ý nghĩa của `--force`. Chi tiết ở [docs/vi/safety.md](docs/vi/safety.md).
466
458
 
467
- **H: Stack của tôi không được hỗ trợ. Tôi có thể thêm không?**
468
- Đ: Có. Stack mới cần ~3 prompt template + một domain scanner. Xem [CONTRIBUTING.md](CONTRIBUTING.md) để có hướng dẫn 8 bước.
459
+ **Q: Stack của tôi chưa được hỗ trợ, có thêm vào được không?**
460
+ A: Được. Một stack mới chỉ cần khoảng 3 prompt template và một domain scanner. Hướng dẫn 8 bước nằm trong [CONTRIBUTING.md](CONTRIBUTING.md).
469
461
 
470
- **H: Làm sao sinh doc bằng tiếng Việt (hoặc ngôn ngữ khác)?**
471
- Đ: `npx claudeos-core init --lang vi`. Hỗ trợ 10 ngôn ngữ: en, ko, ja, zh-CN, es, vi, hi, ru, fr, de.
462
+ **Q: Làm sao sinh docs bằng tiếng Hàn (hoặc ngôn ngữ khác)?**
463
+ A: Chạy `npx claudeos-core init --lang ko` là xong. Có 10 ngôn ngữ được hỗ trợ: en, ko, ja, zh-CN, es, vi, hi, ru, fr, de.
472
464
 
473
- **H: Có chạy với monorepo không?**
474
- Đ: Có — Turborepo (`turbo.json`), pnpm workspaces (`pnpm-workspace.yaml`), Lerna (`lerna.json`) và npm/yarn workspaces (`package.json#workspaces`) được stack-detector phát hiện. Mỗi app được phân tích riêng. Các layout monorepo khác (ví dụ NX) không được phát hiện đặc biệt, nhưng các pattern chung `apps/*/` và `packages/*/` vẫn được scanner theo từng stack nhặt được.
465
+ **Q: Có dùng được với monorepo không?**
466
+ A: Có. Stack-detector nhận diện Turborepo (`turbo.json`), pnpm workspaces (`pnpm-workspace.yaml`), Lerna (`lerna.json`) và npm/yarn workspaces (`package.json#workspaces`). Mỗi app có phần phân tích riêng. Một số layout monorepo khác như NX tuy chưa có nhánh detect riêng, nhưng pattern chung `apps/*/` và `packages/*/` thì scanner theo từng stack vẫn nhận ra được.
467
+
468
+ **Q: Nếu Claude Code sinh ra rule mà tôi không đồng ý thì sao?**
469
+ A: Cứ sửa trực tiếp. Sau đó chạy `npx claudeos-core lint` để chắc rằng cấu trúc CLAUDE.md vẫn hợp lệ. Phần chỉnh sửa tay sẽ được giữ qua các lần `init` sau (miễn không kèm `--force`), vì cơ chế resume sẽ skip những pass đã có marker.
470
+
471
+ **Q: Báo bug ở đâu?**
472
+ A: Tại [GitHub Issues](https://github.com/claudeos-core/claudeos-core/issues). Các vấn đề bảo mật xin xem [SECURITY.md](SECURITY.md).
473
+
474
+ ---
475
475
 
476
- **H: Nếu Claude Code sinh ra rule mà tôi không đồng ý thì sao?**
477
- Đ: Sửa trực tiếp. Sau đó chạy `npx claudeos-core lint` để kiểm tra CLAUDE.md vẫn đúng cấu trúc. Các chỉnh sửa của bạn được giữ qua các lần `init` sau (không có `--force`) — cơ chế resume bỏ qua các pass đã có marker.
476
+ ## Nếu điều này tiết kiệm thời gian cho bạn
478
477
 
479
- **H: Báo bug ở đâu?**
480
- Đ: [GitHub Issues](https://github.com/claudeos-core/claudeos-core/issues). Vấn đề bảo mật xem [SECURITY.md](SECURITY.md).
478
+ Một ⭐ trên GitHub giúp dự án dễ được nhìn thấy hơn và giúp người khác tìm tới. Issue, PR và đóng góp stack template đều rất được hoan nghênh. Chi tiết trong [CONTRIBUTING.md](CONTRIBUTING.md).
481
479
 
482
480
  ---
483
481
 
484
- ## Documentation
482
+ ## Tài liệu
485
483
 
486
- | Chủ đề | Đọc tại |
484
+ | Chủ đề | Đọc ở đâu |
487
485
  |---|---|
488
- | Cách pipeline 4-pass hoạt động (sâu hơn diagram) | [docs/vi/architecture.md](docs/vi/architecture.md) |
489
- | Diagram trực quan (Mermaid) của kiến trúc | [docs/vi/diagrams.md](docs/vi/diagrams.md) |
490
- | Phát hiện stack — mỗi scanner tìm gì | [docs/vi/stacks.md](docs/vi/stacks.md) |
486
+ | Pipeline 4-pass hoạt động ra sao (sâu hơn diagram) | [docs/vi/architecture.md](docs/vi/architecture.md) |
487
+ | Diagram trực quan của kiến trúc (Mermaid) | [docs/vi/diagrams.md](docs/vi/diagrams.md) |
488
+ | Stack detection — mỗi scanner nhìn vào đâu | [docs/vi/stacks.md](docs/vi/stacks.md) |
491
489
  | Memory layer — decision log và failure pattern | [docs/vi/memory-layer.md](docs/vi/memory-layer.md) |
492
490
  | Chi tiết cả 5 validator | [docs/vi/verification.md](docs/vi/verification.md) |
493
- | Mọi lệnh CLI và tùy chọn | [docs/vi/commands.md](docs/vi/commands.md) |
494
- | Cài thủ công (không dùng `npx`) | [docs/vi/manual-installation.md](docs/vi/manual-installation.md) |
495
- | Override scanner — `.claudeos-scan.json` | [docs/vi/advanced-config.md](docs/vi/advanced-config.md) |
496
- | An toàn: cái gì được giữ khi re-init | [docs/vi/safety.md](docs/vi/safety.md) |
497
- | So sánh với các công cụ tương tự (về phạm vi, không phải chất lượng) | [docs/vi/comparison.md](docs/vi/comparison.md) |
498
- | Lỗi và cách phục hồi | [docs/vi/troubleshooting.md](docs/vi/troubleshooting.md) |
491
+ | Tất cả lệnh CLI và option | [docs/vi/commands.md](docs/vi/commands.md) |
492
+ | Cài đặt thủ công (không qua `npx`) | [docs/vi/manual-installation.md](docs/vi/manual-installation.md) |
493
+ | Override scanner qua `.claudeos-scan.json` | [docs/vi/advanced-config.md](docs/vi/advanced-config.md) |
494
+ | An toàn: cái gì được giữ lại khi re-init | [docs/vi/safety.md](docs/vi/safety.md) |
495
+ | So sánh với các công cụ tương tự (về scope, không phải chất lượng) | [docs/vi/comparison.md](docs/vi/comparison.md) |
496
+ | Lỗi thường gặp và cách khôi phục | [docs/vi/troubleshooting.md](docs/vi/troubleshooting.md) |
499
497
 
500
498
  ---
501
499
 
502
500
  ## Đóng góp
503
501
 
504
- Chào đón đóng góp — thêm hỗ trợ stack, cải thiện prompt, sửa bug. Xem [CONTRIBUTING.md](CONTRIBUTING.md).
502
+ Mọi đóng góp đều được hoan nghênh. Thêm hỗ trợ stack mới, cải thiện prompt, fix bug — đều rất tốt. Chi tiết trong [CONTRIBUTING.md](CONTRIBUTING.md).
505
503
 
506
- Quy tắc ứng xử và chính sách bảo mật xem [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) và [SECURITY.md](SECURITY.md).
504
+ Code of Conduct và policy bảo mật có ở [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) và [SECURITY.md](SECURITY.md).
507
505
 
508
- ## License
506
+ ## Giấy phép
509
507
 
510
- [ISC](LICENSE) — miễn phí cho mọi mục đích, kể cả thương mại.
508
+ [ISC License](LICENSE). Miễn phí cho mọi mục đích sử dụng, kể cả thương mại. © 2025–2026 ClaudeOS-Core contributors.
511
509
 
512
510
  ---
513
511
 
514
- <sub>Xây dựng tận tâm bởi [@claudeos-core](https://github.com/claudeos-core). Nếu công cụ này tiết kiệm thời gian cho bạn, một ⭐ trên GitHub giúp nó được nhiều người biết đến.</sub>
512
+ <sub>Dự án được duy trì bởi team [claudeos-core](https://github.com/claudeos-core). Issue và PR gửi về <https://github.com/claudeos-core/claudeos-core>.</sub>