ai-developer-skill-os 9.1.2 → 9.3.0
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.
- package/.agents/AGENTS.md +139 -42
- package/.agents/DEV_PROFILE.md +95 -0
- package/.agents/registry/capability-graph.yml +171 -334
- package/.agents/registry/graph.json +37 -19
- package/.agents/registry/index.yaml +59 -13
- package/.agents/registry/skills-index.yml +204 -447
- package/.agents/rules/coding.md +23 -0
- package/.agents/rules/global.md +44 -30
- package/.agents/skills/_template/SKILL.md +2 -377
- package/.agents/skills/qk-access-policy/SKILL.md +98 -473
- package/.agents/skills/qk-agent-observability/SKILL.md +3 -439
- package/.agents/skills/qk-ai-builder/SKILL.md +132 -565
- package/.agents/skills/qk-api-consumer/SKILL.md +256 -0
- package/.agents/skills/qk-api-consumer/capability.yaml +21 -0
- package/.agents/skills/qk-api-consumer/evals/scorecard.yaml +29 -0
- package/.agents/skills/qk-api-lifecycle/SKILL.md +133 -456
- package/.agents/skills/qk-bug-resolution/SKILL.md +128 -561
- package/.agents/skills/qk-code-review/SKILL.md +142 -420
- package/.agents/skills/qk-context-loader/SKILL.md +99 -471
- package/.agents/skills/qk-data-engineer/SKILL.md +119 -340
- package/.agents/skills/qk-data-lifecycle/SKILL.md +89 -488
- package/.agents/skills/qk-db-optimizer/SKILL.md +102 -488
- package/.agents/skills/qk-design-system-engineering/SKILL.md +76 -461
- package/.agents/skills/qk-devops-platform/SKILL.md +77 -463
- package/.agents/skills/qk-docs/SKILL.md +88 -494
- package/.agents/skills/qk-engineering-standard/SKILL.md +4 -588
- package/.agents/skills/qk-fe-api-integration/SKILL.md +343 -343
- package/.agents/skills/qk-fe-api-integration/evals/scorecard.yaml +29 -29
- package/.agents/skills/qk-feature-delivery/SKILL.md +137 -445
- package/.agents/skills/qk-feature-delivery/evals/scorecard.yaml +1 -1
- package/.agents/skills/qk-frontend-architecture/SKILL.md +5 -479
- package/.agents/skills/qk-help/evals/scorecard.yaml +13 -13
- package/.agents/skills/qk-orchestrator/SKILL.md +63 -502
- package/.agents/skills/qk-orchestrator/references/routing-table.md +10 -14
- package/.agents/skills/qk-product-specification/SKILL.md +70 -479
- package/.agents/skills/qk-production-release/SKILL.md +80 -537
- package/.agents/skills/qk-project-audit/SKILL.md +174 -0
- package/.agents/skills/qk-project-bootstrap/SKILL.md +243 -471
- package/.agents/skills/qk-project-health/SKILL.md +97 -496
- package/.agents/skills/qk-project-memory/SKILL.md +76 -21
- package/.agents/skills/qk-refactor/SKILL.md +167 -384
- package/.agents/skills/qk-security-audit/SKILL.md +141 -463
- package/.agents/skills/qk-security-audit/capability.yaml +1 -2
- package/.agents/skills/qk-system-evolution/SKILL.md +343 -343
- package/.agents/skills/qk-system-evolution/evals/scorecard.yaml +26 -26
- package/.agents/skills/qk-test-engineering/SKILL.md +119 -509
- package/.agents/skills/qk-ui-audit/SKILL.md +73 -537
- package/.agents/skills/qk-ui-builder/SKILL.md +521 -482
- package/.agents/skills/qk-ui-system-builder/SKILL.md +68 -514
- package/.agents/skills/qk-upgrade/SKILL.md +301 -0
- package/.agents/skills/qk-upgrade/capability.yaml +24 -0
- package/.agents/skills/qk-upgrade/evals/scorecard.yaml +26 -0
- package/.agents/skills/qk-validation-gate/SKILL.md +4 -603
- package/.agents/skills/qk-web-quality-gate/SKILL.md +85 -463
- package/.agents/workflows/bug-resolution.yml +6 -6
- package/.agents/workflows/context-discovery.yml +94 -0
- package/.agents/workflows/feature-delivery.yml +8 -4
- package/.agents/workflows/refactor.yml +6 -3
- package/.agents/workflows/shared/quality-gate.yml +94 -0
- package/.agents/workflows/skin-governance.yml +115 -0
- package/README.md +152 -67
- package/package.json +2 -2
- package/tooling/build-registry.js +30 -8
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
# ── Identity ───────────────────────────────────────────────
|
|
3
3
|
name: qk-engineering-standard
|
|
4
|
-
version: 9.1
|
|
5
|
-
status:
|
|
4
|
+
version: 9.2.1
|
|
5
|
+
status: relocated
|
|
6
6
|
description: "Ép buộc SOLID, DRY, Clean Code với ngưỡng số liệu cụ thể — không có rule mơ hồ."
|
|
7
7
|
platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
|
|
8
8
|
|
|
@@ -83,591 +83,7 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
|
|
|
83
83
|
---
|
|
84
84
|
|
|
85
85
|
# qk-engineering-standard — Code Quality Enforcer
|
|
86
|
-
|
|
87
|
-
> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
|
|
88
|
-
|
|
89
|
-
## Memory Workflow
|
|
90
|
-
|
|
91
|
-
### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
|
|
92
|
-
- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
|
|
93
|
-
- **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
|
|
94
|
-
- **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
|
|
95
|
-
|
|
96
|
-
---
|
|
97
|
-
|
|
98
|
-
### Pre-flight Retrieve (Trước khi thực thi)
|
|
99
|
-
- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
|
|
100
|
-
bắt buộc tra cứu:
|
|
101
|
-
- `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
|
|
102
|
-
|
|
103
|
-
- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
|
|
104
|
-
- Architecture
|
|
105
|
-
- Hard Bug
|
|
106
|
-
- Convention
|
|
107
|
-
- Pattern
|
|
108
|
-
- Tech Debt Pattern
|
|
109
|
-
- 👉 *Domain Focus:* Convention / Architecture (vd: ngưỡng định lượng độ phức tạp cyclomatic, DRY, SOLID).
|
|
110
|
-
|
|
111
|
-
- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
|
|
112
|
-
Không được xem Memory là Source of Truth.
|
|
113
|
-
Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
|
|
114
|
-
|
|
115
|
-
---
|
|
116
|
-
|
|
117
|
-
### Learning Flow (AI tự học có kiểm soát)
|
|
118
|
-
- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
|
|
119
|
-
- Hard Bug có khả năng tái diễn.
|
|
120
|
-
- Pattern làm việc lặp lại trong dự án.
|
|
121
|
-
- Convention hoặc quy tắc kiến trúc mới.
|
|
122
|
-
- Quyết định Architecture quan trọng.
|
|
123
|
-
- Tech Debt Pattern hoặc Code Smell có tính hệ thống.
|
|
124
|
-
- 👉 *Domain Harvest:* Convention hoặc ranh giới kỹ thuật mới (vd: áp đặt giới hạn 100 dòng cho file AGENTS.md).
|
|
125
|
-
|
|
126
|
-
- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
|
|
127
|
-
- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
|
|
128
|
-
- AI không được tự động Promote Candidate Memory thành Project Knowledge.
|
|
129
|
-
|
|
130
|
-
---
|
|
131
|
-
|
|
132
|
-
### Post-flight Harvest (Đề xuất → Phê duyệt)
|
|
133
|
-
Sau khi hoàn thành task:
|
|
134
|
-
- AI đánh giá các Candidate Memory đã tạo.
|
|
135
|
-
- Nếu phát hiện tri thức có giá trị tái sử dụng:
|
|
136
|
-
- Đề xuất người dùng xem xét.
|
|
137
|
-
- Gửi yêu cầu phê duyệt thông qua:
|
|
138
|
-
- `/learn`
|
|
139
|
-
- `qk-project-memory`
|
|
140
|
-
- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
|
|
141
|
-
|
|
142
|
-
```
|
|
143
|
-
.ai-local/candidates/ ──(Approve)──> .ai-local/knowledge/index.yaml
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
|
|
147
|
-
- Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
|
|
148
|
-
|
|
149
|
-
---
|
|
150
|
-
|
|
151
|
-
### Ignore (Không đưa vào Memory)
|
|
152
|
-
Không lưu:
|
|
153
|
-
- Trace log của một session đơn lẻ.
|
|
154
|
-
- Temporary debugging data.
|
|
155
|
-
- Output của một lần chạy test/scan.
|
|
156
|
-
- Report health tạm thời của một đợt kiểm tra.
|
|
157
|
-
- Lỗi nhỏ chỉ xảy ra một lần.
|
|
158
|
-
- Thông tin không có khả năng tái sử dụng.
|
|
159
|
-
- 👉 *Domain Ignore:* Cảnh báo linter tạm thời.
|
|
160
|
-
|
|
161
|
-
---
|
|
162
|
-
|
|
163
|
-
### Golden Rule
|
|
164
|
-
> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
|
|
165
|
-
> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
|
|
166
|
-
|
|
167
|
-
---
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
|
|
172
|
-
- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
|
|
173
|
-
- **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
|
|
174
|
-
- **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
|
|
175
|
-
|
|
176
|
-
---
|
|
177
|
-
|
|
178
|
-
### Pre-flight Retrieve (Trước khi thực thi)
|
|
179
|
-
- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
|
|
180
|
-
bắt buộc tra cứu:
|
|
181
|
-
- `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
|
|
182
|
-
|
|
183
|
-
- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
|
|
184
|
-
- Architecture
|
|
185
|
-
- Hard Bug
|
|
186
|
-
- Convention
|
|
187
|
-
- Pattern
|
|
188
|
-
- Tech Debt Pattern
|
|
189
|
-
- 👉 *Domain Focus:* Convention / Architecture (vd: ngưỡng định lượng độ phức tạp cyclomatic, DRY, SOLID).
|
|
190
|
-
|
|
191
|
-
- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
|
|
192
|
-
Không được xem Memory là Source of Truth.
|
|
193
|
-
Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
|
|
194
|
-
|
|
195
|
-
---
|
|
196
|
-
|
|
197
|
-
### Learning Flow (AI tự học có kiểm soát)
|
|
198
|
-
- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
|
|
199
|
-
- Hard Bug có khả năng tái diễn.
|
|
200
|
-
- Pattern làm việc lặp lại trong dự án.
|
|
201
|
-
- Convention hoặc quy tắc kiến trúc mới.
|
|
202
|
-
- Quyết định Architecture quan trọng.
|
|
203
|
-
- Tech Debt Pattern hoặc Code Smell có tính hệ thống.
|
|
204
|
-
- 👉 *Domain Harvest:* Convention hoặc ranh giới kỹ thuật mới (vd: áp đặt giới hạn 100 dòng cho file AGENTS.md).
|
|
205
|
-
|
|
206
|
-
- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
|
|
207
|
-
- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
|
|
208
|
-
- AI không được tự động Promote Candidate Memory thành Project Knowledge.
|
|
209
|
-
|
|
210
|
-
---
|
|
211
|
-
|
|
212
|
-
### Post-flight Harvest (Đề xuất → Phê duyệt)
|
|
213
|
-
Sau khi hoàn thành task:
|
|
214
|
-
- AI đánh giá các Candidate Memory đã tạo.
|
|
215
|
-
- Nếu phát hiện tri thức có giá trị tái sử dụng:
|
|
216
|
-
- Đề xuất người dùng xem xét.
|
|
217
|
-
- Gửi yêu cầu phê duyệt thông qua:
|
|
218
|
-
- `/learn`
|
|
219
|
-
- `qk-project-memory`
|
|
220
|
-
- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
|
|
221
|
-
|
|
222
|
-
```
|
|
223
|
-
.ai-local/candidates/ ──(Approve)──> .ai-local/knowledge/index.yaml
|
|
224
|
-
```
|
|
225
|
-
|
|
226
|
-
- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
|
|
227
|
-
- Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
|
|
228
|
-
|
|
229
|
-
---
|
|
230
|
-
|
|
231
|
-
### Ignore (Không đưa vào Memory)
|
|
232
|
-
Không lưu:
|
|
233
|
-
- Trace log của một session đơn lẻ.
|
|
234
|
-
- Temporary debugging data.
|
|
235
|
-
- Output của một lần chạy test/scan.
|
|
236
|
-
- Report health tạm thời của một đợt kiểm tra.
|
|
237
|
-
- Lỗi nhỏ chỉ xảy ra một lần.
|
|
238
|
-
- Thông tin không có khả năng tái sử dụng.
|
|
239
|
-
- 👉 *Domain Ignore:* Cảnh báo linter tạm thời.
|
|
240
|
-
|
|
241
|
-
---
|
|
242
|
-
|
|
243
|
-
### Golden Rule
|
|
244
|
-
> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
|
|
245
|
-
> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
|
|
246
|
-
|
|
247
|
-
---
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
### Pre-flight Retrieve (Trước khi thực thi)
|
|
252
|
-
- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
|
|
253
|
-
bắt buộc tra cứu:
|
|
254
|
-
- `.agents/knowledge/index.yaml` (Shared Project Knowledge)
|
|
255
|
-
- `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
|
|
256
|
-
|
|
257
|
-
- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
|
|
258
|
-
- Architecture
|
|
259
|
-
- Hard Bug
|
|
260
|
-
- Convention
|
|
261
|
-
- Pattern
|
|
262
|
-
- Tech Debt Pattern
|
|
263
|
-
- 👉 *Domain Focus:* Convention / Architecture (vd: ngưỡng định lượng độ phức tạp cyclomatic, DRY, SOLID).
|
|
264
|
-
|
|
265
|
-
- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
|
|
266
|
-
Không được xem Memory là Source of Truth.
|
|
267
|
-
Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
|
|
268
|
-
|
|
269
|
-
---
|
|
270
|
-
|
|
271
|
-
### Learning Flow (AI tự học có kiểm soát)
|
|
272
|
-
- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
|
|
273
|
-
- Hard Bug có khả năng tái diễn.
|
|
274
|
-
- Pattern làm việc lặp lại trong dự án.
|
|
275
|
-
- Convention hoặc quy tắc kiến trúc mới.
|
|
276
|
-
- Quyết định Architecture quan trọng.
|
|
277
|
-
- Tech Debt Pattern hoặc Code Smell có tính hệ thống.
|
|
278
|
-
- 👉 *Domain Harvest:* Convention hoặc ranh giới kỹ thuật mới (vd: áp đặt giới hạn 100 dòng cho file AGENTS.md).
|
|
279
|
-
|
|
280
|
-
- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
|
|
281
|
-
- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
|
|
282
|
-
- AI không được tự động Promote Candidate Memory thành Project Knowledge.
|
|
283
|
-
|
|
284
|
-
---
|
|
285
|
-
|
|
286
|
-
### Post-flight Harvest (Đề xuất → Phê duyệt)
|
|
287
|
-
Sau khi hoàn thành task:
|
|
288
|
-
- AI đánh giá các Candidate Memory đã tạo.
|
|
289
|
-
- Nếu phát hiện tri thức có giá trị tái sử dụng:
|
|
290
|
-
- Đề xuất người dùng xem xét.
|
|
291
|
-
- Gửi yêu cầu phê duyệt thông qua:
|
|
292
|
-
- `/learn`
|
|
293
|
-
- `qk-project-memory`
|
|
294
|
-
- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
|
|
295
|
-
|
|
296
|
-
```
|
|
297
|
-
.ai-local/candidates/ ──(Approve)──> .agents/knowledge/index.yaml
|
|
298
|
-
```
|
|
299
|
-
|
|
300
|
-
- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
|
|
301
|
-
- Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
|
|
302
|
-
|
|
303
|
-
---
|
|
304
|
-
|
|
305
|
-
### Ignore (Không đưa vào Memory)
|
|
306
|
-
Không lưu:
|
|
307
|
-
- Trace log của một session đơn lẻ.
|
|
308
|
-
- Temporary debugging data.
|
|
309
|
-
- Output của một lần chạy test/scan.
|
|
310
|
-
- Report health tạm thời của một đợt kiểm tra.
|
|
311
|
-
- Lỗi nhỏ chỉ xảy ra một lần.
|
|
312
|
-
- Thông tin không có khả năng tái sử dụng.
|
|
313
|
-
- 👉 *Domain Ignore:* Cảnh báo linter tạm thời.
|
|
314
|
-
|
|
315
|
-
---
|
|
316
|
-
|
|
317
|
-
### Golden Rule
|
|
318
|
-
> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
|
|
319
|
-
> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
|
|
320
|
-
|
|
321
|
-
---
|
|
322
|
-
---
|
|
323
|
-
|
|
324
|
-
### Learning Flow (AI tự học có kiểm soát)
|
|
325
|
-
- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
|
|
326
|
-
- Hard Bug có khả năng tái diễn.
|
|
327
|
-
- Pattern làm việc lặp lại trong dự án.
|
|
328
|
-
- Convention hoặc quy tắc kiến trúc mới.
|
|
329
|
-
- Quyết định Architecture quan trọng.
|
|
330
|
-
- Tech Debt Pattern hoặc Code Smell có tính hệ thống.
|
|
331
|
-
- 👉 *Domain Harvest:* Convention hoặc ranh giới kỹ thuật mới (vd: áp đặt giới hạn 100 dòng cho file AGENTS.md).
|
|
332
|
-
|
|
333
|
-
- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
|
|
334
|
-
- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
|
|
335
|
-
- AI không được tự động Promote Candidate Memory thành Project Knowledge.
|
|
336
|
-
|
|
337
|
-
---
|
|
338
|
-
|
|
339
|
-
### Post-flight Harvest (Đề xuất → Phê duyệt)
|
|
340
|
-
Sau khi hoàn thành task:
|
|
341
|
-
- AI đánh giá các Candidate Memory đã tạo.
|
|
342
|
-
- Nếu phát hiện tri thức có giá trị tái sử dụng:
|
|
343
|
-
- Đề xuất người dùng xem xét.
|
|
344
|
-
- Gửi yêu cầu phê duyệt thông qua:
|
|
345
|
-
- `/learn`
|
|
346
|
-
- `qk-project-memory`
|
|
347
|
-
- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
|
|
348
|
-
|
|
349
|
-
```
|
|
350
|
-
.ai-local/candidates/ ──(Approve)──> .agents/knowledge/index.yaml
|
|
351
|
-
```
|
|
352
|
-
|
|
353
|
-
- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
|
|
354
|
-
- Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
|
|
355
|
-
|
|
356
|
-
---
|
|
357
|
-
|
|
358
|
-
### Ignore (Không đưa vào Memory)
|
|
359
|
-
Không lưu:
|
|
360
|
-
- Trace log của một session đơn lẻ.
|
|
361
|
-
- Temporary debugging data.
|
|
362
|
-
- Output của một lần chạy test/scan.
|
|
363
|
-
- Report health tạm thời của một đợt kiểm tra.
|
|
364
|
-
- Lỗi nhỏ chỉ xảy ra một lần.
|
|
365
|
-
- Thông tin không có khả năng tái sử dụng.
|
|
366
|
-
- 👉 *Domain Ignore:* Cảnh báo linter tạm thời.
|
|
367
|
-
|
|
368
|
-
---
|
|
369
|
-
|
|
370
|
-
### Golden Rule
|
|
371
|
-
> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
|
|
372
|
-
> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
|
|
373
|
-
|
|
374
|
-
---
|
|
375
|
-
---
|
|
376
86
|
|
|
377
|
-
|
|
378
|
-
- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
|
|
379
|
-
- Hard Bug có khả năng tái diễn.
|
|
380
|
-
- Pattern làm việc lặp lại trong dự án.
|
|
381
|
-
- Convention hoặc quy tắc kiến trúc mới.
|
|
382
|
-
- Quyết định Architecture quan trọng.
|
|
383
|
-
- Tech Debt Pattern hoặc Code Smell có tính hệ thống.
|
|
384
|
-
- 👉 *Domain Harvest:* Convention hoặc ranh giới kỹ thuật mới (vd: áp đặt giới hạn 100 dòng cho file AGENTS.md).
|
|
385
|
-
|
|
386
|
-
- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
|
|
387
|
-
- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
|
|
388
|
-
- AI không được tự động Promote Candidate Memory thành Project Knowledge.
|
|
389
|
-
|
|
390
|
-
---
|
|
391
|
-
|
|
392
|
-
### Post-flight Harvest (Đề xuất → Phê duyệt)
|
|
393
|
-
Sau khi hoàn thành task:
|
|
394
|
-
- AI đánh giá các Candidate Memory đã tạo.
|
|
395
|
-
- Nếu phát hiện tri thức có giá trị tái sử dụng:
|
|
396
|
-
- Đề xuất người dùng xem xét.
|
|
397
|
-
- Gửi yêu cầu phê duyệt thông qua:
|
|
398
|
-
- `/learn`
|
|
399
|
-
- `qk-project-memory`
|
|
400
|
-
- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
|
|
401
|
-
|
|
402
|
-
```
|
|
403
|
-
.ai-local/candidates/ ──(Approve)──> .agents/knowledge/index.yaml
|
|
404
|
-
```
|
|
405
|
-
|
|
406
|
-
- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
|
|
407
|
-
- Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
|
|
408
|
-
|
|
409
|
-
---
|
|
410
|
-
|
|
411
|
-
### Ignore (Không đưa vào Memory)
|
|
412
|
-
Không lưu:
|
|
413
|
-
- Trace log của một session đơn lẻ.
|
|
414
|
-
- Temporary debugging data.
|
|
415
|
-
- Output của một lần chạy test/scan.
|
|
416
|
-
- Report health tạm thời của một đợt kiểm tra.
|
|
417
|
-
- Lỗi nhỏ chỉ xảy ra một lần.
|
|
418
|
-
- Thông tin không có khả năng tái sử dụng.
|
|
419
|
-
- 👉 *Domain Ignore:* Cảnh báo linter tạm thời.
|
|
420
|
-
|
|
421
|
-
---
|
|
422
|
-
|
|
423
|
-
### Golden Rule
|
|
424
|
-
> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
|
|
425
|
-
> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
|
|
426
|
-
|
|
427
|
-
---
|
|
428
|
-
---
|
|
429
|
-
---
|
|
430
|
-
---
|
|
431
|
-
|
|
432
|
-
## Preconditions
|
|
433
|
-
- [ ] Target file(s) or module(s) are specified
|
|
434
|
-
|
|
435
|
-
```
|
|
436
|
-
On missing precondition:
|
|
437
|
-
EXIT: BLOCKED
|
|
438
|
-
Message: "Vui lòng chỉ định file hoặc module cần kiểm tra."
|
|
439
|
-
```
|
|
440
|
-
|
|
441
|
-
## Scope
|
|
442
|
-
- ✅ Detect violations with exact file:line references
|
|
443
|
-
- ✅ Classify by severity with concrete thresholds
|
|
444
|
-
- ✅ Suggest minimal, targeted refactors
|
|
445
|
-
|
|
446
|
-
## Non-Goals
|
|
447
|
-
- ❌ Auto-fix code — report only (fixes go to qk-bug-resolution or qk-feature-delivery)
|
|
448
|
-
- ❌ Rewrite architecture
|
|
449
|
-
- ❌ Touch files outside the specified scope
|
|
450
|
-
|
|
451
|
-
## Concrete Thresholds (Non-Negotiable)
|
|
452
|
-
**Các giới hạn dưới đây được dùng để định lượng vi phạm rác mã (R-C-09) và bảo mật (R-SEC-04):**
|
|
453
|
-
|
|
454
|
-
```yaml
|
|
455
|
-
function:
|
|
456
|
-
max_lines: 30 # Lines of code, excluding comments/blanks
|
|
457
|
-
max_cyclomatic_complexity: 10
|
|
458
|
-
max_parameters: 4
|
|
459
|
-
|
|
460
|
-
file:
|
|
461
|
-
max_lines: 300
|
|
462
|
-
max_public_methods_per_class: 10 # God Class threshold
|
|
463
|
-
|
|
464
|
-
dry:
|
|
465
|
-
violation_threshold: 3 # Same logic duplicated in ≥ 3 places
|
|
466
|
-
|
|
467
|
-
separation_of_concerns:
|
|
468
|
-
violation: "File mixes UI rendering + API calls + State management"
|
|
469
|
-
|
|
470
|
-
naming:
|
|
471
|
-
min_variable_name_length: 2 # Single-letter vars (except i,j,k in loops)
|
|
472
|
-
max_abbreviation_ratio: 0.3 # > 30% abbreviations in identifiers = violation
|
|
473
|
-
|
|
474
|
-
dependency:
|
|
475
|
-
max_imports_per_file: 15 # Beyond this: likely a God File
|
|
476
|
-
```
|
|
477
|
-
|
|
478
|
-
## Priority Order
|
|
479
|
-
|
|
480
|
-
| Priority | Check | Severity | Skip Threshold |
|
|
481
|
-
|----------|-------|----------|----------------|
|
|
482
|
-
| P1 | Security violations (hardcoded secrets, SQL injection) | CRITICAL | Never |
|
|
483
|
-
| P2 | God Functions > 30 lines / complexity > 10 | HIGH | Budget < 30% |
|
|
484
|
-
| P3 | God Files > 300 lines / God Classes | HIGH | Budget < 40% |
|
|
485
|
-
| P4 | DRY violations (3+ duplicates) | MEDIUM | Budget < 50% |
|
|
486
|
-
| P5 | Mixed concerns in single file | MEDIUM | Budget < 60% |
|
|
487
|
-
| P6 | Naming convention violations | LOW | Budget < 70% |
|
|
488
|
-
| P7 | Excessive imports / coupling | LOW | Budget < 80% |
|
|
489
|
-
|
|
490
|
-
## Workflow
|
|
491
|
-
|
|
492
|
-
### Phase 1 — Scan for Critical & High Violations
|
|
493
|
-
|
|
494
|
-
**Steps:**
|
|
495
|
-
1. `grep_search` — search for: hardcoded secrets, `console.log`, `eval(`, `any` types
|
|
496
|
-
2. `view_file[targeted]` — read function definitions to count lines and parameters
|
|
497
|
-
3. Log each violation with Evidence Format
|
|
498
|
-
|
|
499
|
-
**Decision:**
|
|
500
|
-
```
|
|
501
|
-
IF CRITICAL violation found (e.g., hardcoded API key)
|
|
502
|
-
→ Report immediately, mark EXIT: FAILED
|
|
503
|
-
→ Still continue scanning (don't stop at first critical)
|
|
504
|
-
|
|
505
|
-
IF function line count > 30 OR complexity > 10
|
|
506
|
-
→ Log as [HIGH]
|
|
507
|
-
|
|
508
|
-
IF file line count > 300
|
|
509
|
-
→ Log as [HIGH] — God File suspected
|
|
510
|
-
```
|
|
511
|
-
|
|
512
|
-
**Exit When:**
|
|
513
|
-
- All P1+P2+P3 checks done → go to Phase 2
|
|
514
|
-
- Token budget < 30% → go to Phase 3 directly with PARTIAL flag
|
|
515
|
-
|
|
516
|
-
### Phase 2 — Scan for Medium & Low Violations
|
|
517
|
-
|
|
518
|
-
**Steps:**
|
|
519
|
-
1. `grep_search` — find duplicate logic patterns (copy-paste code)
|
|
520
|
-
2. Check import counts per file
|
|
521
|
-
3. Check naming conventions
|
|
522
|
-
|
|
523
|
-
**Decision:**
|
|
524
|
-
```
|
|
525
|
-
IF same logic block appears ≥ 3 times
|
|
526
|
-
→ Log as [MEDIUM] DRY violation
|
|
527
|
-
|
|
528
|
-
IF file has > 15 imports
|
|
529
|
-
→ Log as [LOW] — potential God File or tight coupling
|
|
530
|
-
|
|
531
|
-
IF token budget < 50%
|
|
532
|
-
→ Skip P6+P7, go to Phase 3
|
|
533
|
-
```
|
|
534
|
-
|
|
535
|
-
### Phase 3 — Score & Report
|
|
536
|
-
|
|
537
|
-
**Steps:**
|
|
538
|
-
1. Count violations by severity
|
|
539
|
-
2. Calculate health score: start at 100, deduct per violation
|
|
540
|
-
3. Generate report
|
|
541
|
-
|
|
542
|
-
**Deduction Scale:**
|
|
543
|
-
```
|
|
544
|
-
CRITICAL: -25 pts each
|
|
545
|
-
HIGH: -10 pts each
|
|
546
|
-
MEDIUM: -5 pts each
|
|
547
|
-
LOW: -2 pts each
|
|
548
|
-
```
|
|
549
|
-
|
|
550
|
-
**Decision:**
|
|
551
|
-
```
|
|
552
|
-
IF score ≥ 80 AND no CRITICAL violations
|
|
553
|
-
→ EXIT: SUCCESS
|
|
554
|
-
|
|
555
|
-
IF score 60–79 OR any HIGH violations
|
|
556
|
-
→ EXIT: PARTIAL — list fixes needed
|
|
557
|
-
|
|
558
|
-
IF score < 60 OR any CRITICAL violations
|
|
559
|
-
→ EXIT: FAILED — requires immediate action
|
|
560
|
-
```
|
|
561
|
-
|
|
562
|
-
## Confidence Model
|
|
563
|
-
|
|
564
|
-
| Level | Condition | Action |
|
|
565
|
-
|-------|-----------|--------|
|
|
566
|
-
| HIGH | Direct line count, exact pattern match | Report as violation |
|
|
567
|
-
| MEDIUM | Inferred cyclomatic complexity without tool | Note estimate |
|
|
568
|
-
| LOW | Architectural smell inferred from structure | Mark as "suspected — verify manually" |
|
|
569
|
-
|
|
570
|
-
## Severity
|
|
571
|
-
|
|
572
|
-
| Level | Definition | Example |
|
|
573
|
-
|-------|-----------|---------|
|
|
574
|
-
| CRITICAL | Security risk or data integrity | Hardcoded secret, SQL injection via string concat |
|
|
575
|
-
| HIGH | Technical debt that blocks scaling | Function 80 lines, God Class 15+ methods |
|
|
576
|
-
| MEDIUM | DRY or SoC violation, fixable in < 1 hour | Same validation logic in 3 components |
|
|
577
|
-
| LOW | Style/naming issue, non-blocking | Single-letter variable `x` outside loop |
|
|
578
|
-
|
|
579
|
-
## Evidence Format
|
|
580
|
-
|
|
581
|
-
```
|
|
582
|
-
[SEVERITY] path/to/file.ts:LINE
|
|
583
|
-
Rule: [FUNCTION_LENGTH | COMPLEXITY | DRY | SOC | NAMING | GOD_CLASS | SECRET]
|
|
584
|
-
Reason: [specific measurement vs threshold]
|
|
585
|
-
Confidence: [HIGH|MEDIUM|LOW]
|
|
586
|
-
Fix: [one-line suggestion]
|
|
587
|
-
Deduction: -N pts
|
|
588
|
-
```
|
|
589
|
-
|
|
590
|
-
**Example:**
|
|
591
|
-
```
|
|
592
|
-
[HIGH] src/services/order.service.ts:45
|
|
593
|
-
Rule: FUNCTION_LENGTH
|
|
594
|
-
Reason: Function `processOrder` is 87 lines (threshold: 30)
|
|
595
|
-
Confidence: HIGH
|
|
596
|
-
Fix: Extract payment logic to `processPayment()`, shipping to `scheduleShipment()`
|
|
597
|
-
Deduction: -10 pts
|
|
598
|
-
```
|
|
599
|
-
|
|
600
|
-
## Retry Policy
|
|
601
|
-
```
|
|
602
|
-
Audit is read-only — no retry needed.
|
|
603
|
-
If file is inaccessible → skip and note in report as PARTIAL.
|
|
604
|
-
```
|
|
605
|
-
|
|
606
|
-
## Escalation Rules
|
|
607
|
-
|
|
608
|
-
```
|
|
609
|
-
BLOCKED: No target specified
|
|
610
|
-
Missing:
|
|
611
|
-
- File path or module name to audit
|
|
612
|
-
Questions:
|
|
613
|
-
1. Bạn muốn kiểm tra file nào hoặc toàn bộ module nào?
|
|
614
|
-
2. Có ngưỡng cụ thể nào bạn muốn thay đổi không? (mặc định: 30 lines/function)
|
|
615
|
-
```
|
|
616
|
-
|
|
617
|
-
## Handoff Contract
|
|
618
|
-
|
|
619
|
-
### Consumes
|
|
620
|
-
```json
|
|
621
|
-
{
|
|
622
|
-
"from": "user or qk-orchestrator",
|
|
623
|
-
"required_fields": ["target_files_or_module"],
|
|
624
|
-
"optional_fields": ["custom_thresholds"]
|
|
625
|
-
}
|
|
626
|
-
```
|
|
627
|
-
|
|
628
|
-
### Produces
|
|
629
|
-
```json
|
|
630
|
-
{
|
|
631
|
-
"to": "user",
|
|
632
|
-
"output_fields": ["health_score", "violations_list", "severity_counts", "exit_code"]
|
|
633
|
-
}
|
|
634
|
-
```
|
|
635
|
-
|
|
636
|
-
## Output Format
|
|
637
|
-
|
|
638
|
-
```
|
|
639
|
-
⚙️ Engineering Standard Audit
|
|
640
|
-
─────────────────────────────────────────────────
|
|
641
|
-
Target: [file or module]
|
|
642
|
-
|
|
643
|
-
Health Score: [X/100]
|
|
644
|
-
CRITICAL violations: [N] (-Npts)
|
|
645
|
-
HIGH violations: [N] (-Npts)
|
|
646
|
-
MEDIUM violations: [N] (-Npts)
|
|
647
|
-
LOW violations: [N] (-Npts)
|
|
648
|
-
|
|
649
|
-
Violations (priority order):
|
|
650
|
-
[SEVERITY] file:LINE — Rule — reason — Fix — (-Xpts)
|
|
651
|
-
|
|
652
|
-
Required Actions:
|
|
653
|
-
1. [Most critical fix]
|
|
654
|
-
2. [Second fix]
|
|
655
|
-
|
|
656
|
-
Exit Code: [SUCCESS | PARTIAL | FAILED]
|
|
657
|
-
```
|
|
658
|
-
|
|
659
|
-
## Exit Codes
|
|
660
|
-
|
|
661
|
-
| Code | Meaning | When |
|
|
662
|
-
|------|---------|------|
|
|
663
|
-
| SUCCESS | Score ≥ 80, no CRITICAL | Code meets V7.5 standards |
|
|
664
|
-
| PARTIAL | Score 60–79 or incomplete scan | Some categories skipped |
|
|
665
|
-
| BLOCKED | No target specified | Cannot audit without scope |
|
|
666
|
-
| FAILED | Score < 60 or CRITICAL found | Immediate action required |
|
|
667
|
-
|
|
668
|
-
## References
|
|
669
|
-
- Detailed thresholds with rationale: `references/thresholds.md`
|
|
670
|
-
- Anti-Patterns Blacklist: `references/anti-patterns.md`
|
|
671
|
-
|
|
672
|
-
---
|
|
87
|
+
> **⚠️ ARCHIVED (v9.2.1):** Downgraded thành rule. Nội dung đã được merge vào `.agents/rules/coding.md` (R-C-10). Không cần gọi trực tiếp — áp dụng tự động trong mọi skill có `side_effects: edit_files`.
|
|
673
88
|
|
|
89
|
+
> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
|