@elvis1513/auto-coding-skill 2.0.4 → 2.0.5

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/README.md CHANGED
@@ -23,6 +23,13 @@ npm install -g git+https://github.com/elvis1513/auto-coding-skill.git
23
23
 
24
24
  ## Release Notes
25
25
 
26
+ ### v2.0.5
27
+
28
+ - Added generic engineering-structure governance: `docs/architecture/structure-standard.md`, ADR template, project health baseline, and optimization backlog templates.
29
+ - Added `ap.py structure-check --scope auto|changed|standard|full` for large-file thresholds, large-file growth blocking, function-size warnings, and baseline-doc checks.
30
+ - Integrated `structure-check` into `light-gate` when `structure.enabled: true` or `commands.structure_check` is configured.
31
+ - Added baseline-aware optimization policy so “optimization complete” means scoped P0/P1/P2 closure plus tracked/accepted remaining debt, not “no future optimizations exist.”
32
+
26
33
  ### v2.0.4
27
34
 
28
35
  - Added a generic impact-aware gate engine: `ap.py impact`, `light-gate --scope auto|changed|standard|full`, and `--explain`.
@@ -156,6 +163,8 @@ It must be committed to Git. Do not add it to `.gitignore`.
156
163
  - `workflow.mode`
157
164
  - `commands.*`
158
165
  - `gate.*`
166
+ - `structure.*`
167
+ - `optimization.*`
159
168
  - `target_env.*`
160
169
  - `jenkins.*`
161
170
  - `docs.*`
@@ -189,6 +198,9 @@ It must be committed to Git. Do not add it to `.gitignore`.
189
198
  4. Start AI development by constraints:
190
199
 
191
200
  - `docs/ENGINEERING.md`
201
+ - `docs/architecture/structure-standard.md`
202
+ - `docs/reviews/project-health-baseline.md`
203
+ - `docs/reviews/optimization-backlog.md`
192
204
  - `docs/tasks/taskbook.md`
193
205
  - `docs/tasks/closure-log.md`
194
206
  - `docs/interfaces/**`
@@ -211,6 +223,26 @@ It must be committed to Git. Do not add it to `.gitignore`.
211
223
  - If the client cannot run subagents, execute the same role sequence in the main agent.
212
224
  - Keep one main agent responsible for scope, integration, quality gates, docs closure, git state, and final delivery.
213
225
 
226
+ ## Structure Governance
227
+
228
+ The default project scaffold includes a generic professional structure standard:
229
+
230
+ - `docs/architecture/structure-standard.md`: layer boundaries, reuse-first rules, file/function size rules, and review priority definitions.
231
+ - `docs/architecture/adr/_TEMPLATE-ADR.md`: architectural decision record template.
232
+ - `docs/reviews/project-health-baseline.md`: accepted current structure, closed optimizations, accepted debt, and completion standard.
233
+ - `docs/reviews/optimization-backlog.md`: ongoing P0/P1/P2/P3 optimization backlog.
234
+
235
+ Useful commands:
236
+
237
+ ```bash
238
+ python3 docs/tools/autopipeline/ap.py structure-check --scope auto
239
+ python3 docs/tools/autopipeline/ap.py structure-check --scope full
240
+ python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
241
+ ```
242
+
243
+ `structure-check` is intentionally generic. Project-specific paths and stricter rules belong in `docs/ENGINEERING.md` under `structure.*`, `optimization.*`, and optional `commands.structure_check`.
244
+ Historical large-file debt can be listed in `structure.accepted_debt_paths` after it is recorded in the health baseline or optimization backlog; continued large additions to those files still fail.
245
+
214
246
  ## AGENTS.md Constraint Example
215
247
 
216
248
  ```md
@@ -218,7 +250,11 @@ It must be committed to Git. Do not add it to `.gitignore`.
218
250
  - Always use `auto-coding-skill` for implementation tasks.
219
251
  - Before any code change, read and obey:
220
252
  1) docs/ENGINEERING.md
221
- 2) docs/tasks/taskbook.md
253
+ 2) docs/architecture/structure-standard.md
254
+ 3) docs/tasks/taskbook.md
255
+ - Before any optimization review, also read:
256
+ 1) docs/reviews/project-health-baseline.md
257
+ 2) docs/reviews/optimization-backlog.md
222
258
  - Execute workflow commands using `python3 docs/tools/autopipeline/ap.py`.
223
259
  - If required docs are missing, create/update docs first, then code.
224
260
 
@@ -244,12 +280,21 @@ It must be committed to Git. Do not add it to `.gitignore`.
244
280
  ## Default Gate Policy
245
281
  - Default local gate is lightweight only.
246
282
  - Use `python3 docs/tools/autopipeline/ap.py impact --scope auto` to inspect changed files, matched project rules, and selected gate scope.
283
+ - Use `python3 docs/tools/autopipeline/ap.py structure-check --scope auto` to catch file growth, large-file extension, and missing structure baseline docs.
247
284
  - Use `python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain` for small-step development after a project declares `gate.default_scope: auto`, `commands.gate_changed`, or matching `gate.rules`.
248
285
  - Use `light-gate --scope standard` for the backward-compatible configured gate, and `light-gate --scope full` before release/deploy-sensitive closure.
249
286
  - The gate engine is generic. Project-specific path mapping belongs in `docs/ENGINEERING.md` under `gate.rules`; unknown or high-risk impact should upgrade to standard/full rather than silently skipping checks.
287
+ - The structure gate is generic. Project-specific thresholds and accepted generated/vendor paths belong in `docs/ENGINEERING.md` under `structure.*`.
250
288
  - Do not require local Docker Compose or full local regression unless the task explicitly needs local runtime diagnosis.
251
289
  - In `dev` mode, push is the finish line after `DEV-CLOSED` is recorded.
252
290
  - In `verify` mode, Jenkins success, target environment verification, and closure record are mandatory.
291
+
292
+ ## Structure Policy
293
+ - Before coding, identify the right layer and reuse points.
294
+ - Do not add new responsibilities to already-large files.
295
+ - Prefer existing libraries, helpers, components, and scripts over new local frameworks.
296
+ - Self-built concurrency/performance/tooling primitives require a reason plus tests or runtime evidence.
297
+ - For optimization review, read the health baseline and backlog first; accepted debt is not a fresh blocker.
253
298
  ```
254
299
 
255
300
  ## Docs Structure and Recording Rules
@@ -269,34 +314,51 @@ It must be committed to Git. Do not add it to `.gitignore`.
269
314
  - Purpose: master task ledger.
270
315
  - How to record:
271
316
  - Every task writes scope, risk, impact area, minimal design note, acceptance, evidence links.
317
+ - For code changes, record structure placement, reuse check, and whether ADR is needed.
272
318
 
273
319
  ### 3) docs/tasks/closure-log.md
274
320
  - Purpose: default lightweight closure record.
275
321
  - How to record:
276
322
  - Append one record per task.
277
- - Required fields: task, commit, Jenkins build, target env verification, result, follow-up.
323
+ - Required fields: task, commit, Jenkins build, target env verification, structure check, result, follow-up.
278
324
  - If Jenkins failed then was fixed, also record failure reason and fix commit.
279
325
 
280
- ### 4) docs/design/
326
+ ### 4) docs/architecture/
327
+ - Files:
328
+ - `docs/architecture/structure-standard.md`
329
+ - `docs/architecture/adr/_TEMPLATE-ADR.md`
330
+ - Rule:
331
+ - Read the structure standard before adding or relocating code.
332
+ - Create an ADR for decisions that affect long-term structure, module boundaries, framework-like helpers, or major tradeoffs.
333
+
334
+ ### 5) docs/reviews/
335
+ - Files:
336
+ - `docs/reviews/project-health-baseline.md`
337
+ - `docs/reviews/optimization-backlog.md`
338
+ - Rule:
339
+ - Structure and optimization reviews must read these before listing findings.
340
+ - Accepted debt is not a fresh blocker unless it worsened or needs priority upgrade.
341
+
342
+ ### 6) docs/design/
281
343
  - Purpose: DD for cross-module / API / DB / deployment / Jenkins / key-page-flow changes.
282
344
  - How to record:
283
345
  - Small changes do not need a standalone DD file.
284
346
  - Higher-risk changes create `docs/design/<TASK_ID>-<slug>.md`.
285
347
 
286
- ### 5) docs/interfaces/
348
+ ### 7) docs/interfaces/
287
349
  - Files:
288
350
  - `docs/interfaces/api.md`
289
351
  - `docs/interfaces/api-change-log.md`
290
352
  - Rule:
291
353
  - Any API change updates both files in the same task.
292
354
 
293
- ### 6) docs/testing/regression-matrix.md
355
+ ### 8) docs/testing/regression-matrix.md
294
356
  - Purpose: on-demand regression evidence, not default gate for every small change.
295
357
  - Rule:
296
358
  - Only real executed items can be marked `PASS`.
297
359
  - `check-matrix` is used only when full regression is explicitly required.
298
360
 
299
- ### 7) docs/tasks/summaries/
361
+ ### 9) docs/tasks/summaries/
300
362
  - Purpose: optional long-form summary.
301
363
  - Rule:
302
364
  - Only for high-risk changes, milestones, or tasks that need full retrospective.
@@ -9,19 +9,22 @@ developer_instructions = """
9
9
 
10
10
  工作要求:
11
11
  1. 优先用 rg / git / 项目脚本快速定位真实入口,再向下追踪调用链。
12
- 2. 先读项目已有文档、配置、路由、任务记录,再做结论。
13
- 3. 如果根因依赖外部库、框架或版本行为,标记需要 docs_researcher / Context7 继续核对,不要凭记忆猜。
14
- 4. 输出内容必须尽量具体到:
12
+ 2. 先读项目已有文档、配置、路由、任务记录;涉及结构/优化时还要读结构标准、健康基线和优化 backlog。
13
+ 3. 输出根因时说明当前代码应归属的层级、现有同类模块、可复用 helper / 组件 / 脚本。
14
+ 4. 如果根因依赖外部库、框架或版本行为,标记需要 docs_researcher / Context7 继续核对,不要凭记忆猜。
15
+ 5. 输出内容必须尽量具体到:
15
16
  - 文件路径
16
17
  - 函数名 / 方法名
17
18
  - 关键结构体 / 类 / 接口
18
19
  - 关键配置项
19
- 5. 不要泛泛而谈,不要直接给大段修复方案。
20
- 6. 输出格式:
20
+ 6. 不要泛泛而谈,不要直接给大段修复方案。
21
+ 7. 输出格式:
21
22
  - 问题入口
22
23
  - 调用链
23
24
  - 关键文件
25
+ - 当前层级 / 归属模块
26
+ - 既有复用点
24
27
  - 根因候选
25
28
  - 建议交给哪个代理继续处理
26
- 7. 优先快速精准搜索,避免全仓库无差别扫描。
29
+ 8. 优先快速精准搜索,避免全仓库无差别扫描。
27
30
  """
@@ -12,14 +12,16 @@ developer_instructions = """
12
12
  2. 坚持“最小可辩护修改”原则。
13
13
  3. 除非明确要求,否则不要重构、不做大面积改名、不改无关文件。
14
14
  4. 先跟随项目现有模式、helper、组件、脚本和文档约束,不新造不必要抽象。
15
- 5. 如果修改依赖外部 API / 版本行为,先让 docs_researcher / 文档 MCP 兜底确认。
16
- 6. 如果修改影响 UI,交给 browser_debugger 或主代理做真实浏览器验证。
17
- 7. 如果修改涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界,交给 reviewer / 安全能力做只读复核。
18
- 8. 修改后运行聚焦门禁:优先项目 light gate,其次相关测试、typecheck、lint、git diff --check。
19
- 9. 修改后输出:
15
+ 5. 改代码前先确认业务层、应用层、基础设施层、接口/UI层、shared/tooling 的正确落位;不要把新职责塞进已经偏大的文件。
16
+ 6. 新增工具、并发/缓存/请求封装、格式转换、权限判断、校验逻辑前,先搜索既有 helper、库、组件和脚本。
17
+ 7. 如果修改依赖外部 API / 版本行为,先让 docs_researcher / 文档 MCP 兜底确认。
18
+ 8. 如果修改影响 UI,交给 browser_debugger 或主代理做真实浏览器验证。
19
+ 9. 如果修改涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界,交给 reviewer / 安全能力做只读复核。
20
+ 10. 修改后运行聚焦门禁:优先项目 light gate,其次 structure-check、相关测试、typecheck、lint、git diff --check。
21
+ 11. 修改后输出:
20
22
  - 修改文件
21
23
  - 修改点
22
24
  - 修改原因
23
25
  - 验证方法
24
- 10. 如发现问题超出小修范围,要立即停止并上报,不要自行扩大战场。
26
+ 12. 如发现问题超出小修范围,要立即停止并上报,不要自行扩大战场。
25
27
  """
@@ -9,14 +9,15 @@ developer_instructions = """
9
9
 
10
10
  工作要求:
11
11
  1. 优先检查:正确性、安全性、边界条件、异常路径、并发风险、事务一致性、缓存一致性、兼容性。
12
- 2. 涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界时,优先使用可用的安全扫描 / security review 能力辅助复核。
13
- 3. 以 git diff、相关测试、接口契约、真实运行证据为基础,不凭风格偏好输出问题。
14
- 4. 优先输出真实问题,不要输出样式洁癖式意见。
15
- 5. 每条问题尽量包含:
12
+ 2. 结构/优化 review 必须先读 project-health-baseline 和 optimization-backlog;不要把 accepted debt 重新报告为当前 blocker。
13
+ 3. 涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界时,优先使用可用的安全扫描 / security review 能力辅助复核。
14
+ 4. 以 git diff、相关测试、接口契约、真实运行证据、结构标准为基础,不凭风格偏好输出问题。
15
+ 5. 优先输出真实问题,不要输出样式洁癖式意见。
16
+ 6. 每条问题尽量包含:
16
17
  - 问题点
17
18
  - 影响范围
18
19
  - 复现条件
19
20
  - 建议修法
20
- 6. 发现测试不足时,指出应补哪些测试或验证路径。
21
- 7. 结论要按严重程度排序:高 / 中 / 低。
21
+ 7. 发现测试不足时,指出应补哪些测试或验证路径。
22
+ 8. 结论要按严重程度排序:P0 / P1 / P2 / P3,并明确是否影响当前任务完成。
22
23
  """
@@ -79,6 +79,8 @@ This contains all manual fields:
79
79
  - `workflow.mode`
80
80
  - `commands.*`
81
81
  - `gate.*`
82
+ - `structure.*`
83
+ - `optimization.*`
82
84
  - `runtime.*` (only for optional local diagnostics)
83
85
  - `target_env.*`
84
86
  - `jenkins.*`
@@ -126,13 +128,14 @@ Read `workflow.mode` from `docs/ENGINEERING.md` before choosing the path.
126
128
  `dev` mode:
127
129
 
128
130
  1) read `docs/ENGINEERING.md`
129
- 2) read / update `docs/tasks/taskbook.md`
130
- 3) write minimal design notes; create a DD only when the change is cross-module, API, DB, deployment, Jenkins, or key-page-flow related
131
- 4) implement only the necessary changes
132
- 5) run the default local lightweight gate
133
- 6) append `docs/tasks/closure-log.md` with `Result: DEV-CLOSED`
134
- 7) commit + push
135
- 8) stop and start the next development task
131
+ 2) read `docs/architecture/structure-standard.md` when the change adds or relocates code
132
+ 3) read / update `docs/tasks/taskbook.md`
133
+ 4) write minimal design notes; create a DD or ADR only when the change is cross-module, API, DB, deployment, Jenkins, key-page-flow, or long-term structure related
134
+ 5) implement only the necessary changes
135
+ 6) run the default local lightweight gate
136
+ 7) append `docs/tasks/closure-log.md` with `Result: DEV-CLOSED`
137
+ 8) commit + push
138
+ 9) stop and start the next development task
136
139
 
137
140
  `verify` mode:
138
141
 
@@ -151,6 +154,7 @@ Default commands:
151
154
  ```bash
152
155
  python3 docs/tools/autopipeline/ap.py doctor
153
156
  python3 docs/tools/autopipeline/ap.py impact --scope auto
157
+ python3 docs/tools/autopipeline/ap.py structure-check --scope auto
154
158
  python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
155
159
  python3 docs/tools/autopipeline/ap.py light-gate --scope full
156
160
  python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
@@ -164,14 +168,27 @@ On-demand commands:
164
168
  python3 docs/tools/autopipeline/ap.py runtime-up
165
169
  python3 docs/tools/autopipeline/ap.py wait-health --scope runtime
166
170
  python3 docs/tools/autopipeline/ap.py runtime-down
171
+ python3 docs/tools/autopipeline/ap.py structure-check --scope full
167
172
  python3 docs/tools/autopipeline/ap.py check-matrix
168
173
  python3 docs/tools/autopipeline/ap.py gen-summary <TASK_ID>
169
174
  ```
170
175
 
176
+ ## Engineering structure policy
177
+
178
+ - Before coding, locate the existing layer, module owner, helper APIs, scripts, and tests for the behavior being changed.
179
+ - Put new code in the correct layer: domain rules stay out of controllers/pages, orchestration belongs in application/service/usecase code, external systems belong behind infrastructure adapters, and UI components should not own deep business workflows.
180
+ - Reuse before building: search existing utilities, components, clients, validation, permissions, caching, retry, formatting, and automation scripts before adding another helper.
181
+ - Do not add new responsibilities to large files. If a file exceeds `structure.max_file_lines_warn`, prefer extracting a focused module or component; if it exceeds `structure.max_file_lines_block`, only small fixes are acceptable unless the path is explicitly allowed.
182
+ - Historical large files can be listed in `structure.accepted_debt_paths` only after they are recorded in the health baseline or optimization backlog; this does not permit large new additions to those files.
183
+ - Self-built algorithms, concurrency controls, caches, protocol clients, or framework-like helpers require a concrete reason such as performance, concurrency, offline/deploy constraints, licensing, security, or compatibility, plus tests or benchmark/runtime evidence.
184
+ - For structural reviews, read `docs/reviews/project-health-baseline.md` and `docs/reviews/optimization-backlog.md` first. Do not re-report accepted debt as a fresh blocker; report only new, worsened, unrecorded P0/P1, or backlog items that now deserve priority upgrade.
185
+ - “Optimization complete” means the scoped P0/P1/P2 work is closed, local gate passes, no new unclassified P0/P1 exists, and remaining P2/P3 work is tracked or accepted debt.
186
+
171
187
  ## Quality policy
172
188
 
173
189
  - Default local gate is lightweight and time-bounded: prefer one curated project command via `commands.light_gate`, then run only diff/API/Jenkins checks.
174
190
  - For small-step development, prefer the generic impact-aware gate: `light-gate --scope auto`. The skill provides the gate engine; each project owns its commands and optional `gate.rules` path mapping in `docs/ENGINEERING.md`.
191
+ - `light-gate` automatically runs `structure-check` when `structure.enabled: true` or `commands.structure_check` is configured.
175
192
  - Keep `standard` as the backward-compatible default when no `gate.*` policy is configured. Use `changed` only when project commands/rules make the reduced scope explicit.
176
193
  - Automatically upgrade to `full` for CI/deploy/build-tool/lockfile/autopipeline config changes, project-declared full rules, unknown impact when configured, or release/verify tasks.
177
194
  - `workflow.mode: dev` closes development after light gate, closure record, commit, and push.
@@ -16,6 +16,7 @@ commands:
16
16
  gate_changed: ""
17
17
  gate_standard: ""
18
18
  gate_full: ""
19
+ structure_check: ""
19
20
  light_gate: ""
20
21
  build: ""
21
22
  test: ""
@@ -53,6 +54,46 @@ gate:
53
54
  - "settings.gradle*"
54
55
  rules: []
55
56
 
57
+ structure:
58
+ enabled: true
59
+ architecture_standard: "clean-architecture-ddd-lite"
60
+ max_file_lines_warn: 800
61
+ max_file_lines_block: 1500
62
+ max_function_lines_warn: 120
63
+ max_added_lines_to_large_file: 80
64
+ require_reuse_search: true
65
+ block_new_responsibility_in_large_file: true
66
+ allow_large_files:
67
+ - ".agents/skills/**"
68
+ - ".claude/skills/**"
69
+ - "docs/tools/autopipeline/**"
70
+ - "generated/**"
71
+ - "**/generated/**"
72
+ - "**/__generated__/**"
73
+ - "vendor/**"
74
+ - "dist/**"
75
+ - "build/**"
76
+ - "target/**"
77
+ - "node_modules/**"
78
+ - "**/*.generated.*"
79
+ - "**/*.gen.*"
80
+ - "**/*.min.js"
81
+ - "**/*.bundle.js"
82
+ - "**/*.map"
83
+ accepted_debt_paths: []
84
+ reusable_tool_dirs:
85
+ - "docs/tools/**"
86
+ - "scripts/**"
87
+ - "tools/**"
88
+ - "packages/*/src/**"
89
+ - "src/**/shared/**"
90
+ - "src/**/utils/**"
91
+
92
+ optimization:
93
+ completion_policy: "baseline-aware"
94
+ require_baseline_for_global_review: true
95
+ report_accepted_debt_as_findings: false
96
+
56
97
  runtime:
57
98
  docker_compose_file: ""
58
99
  docker_service: ""
@@ -92,6 +133,10 @@ docs:
92
133
  closure_log: "docs/tasks/closure-log.md"
93
134
  design_dir: "docs/design"
94
135
  review_dir: "docs/reviews"
136
+ health_baseline: "docs/reviews/project-health-baseline.md"
137
+ optimization_backlog: "docs/reviews/optimization-backlog.md"
138
+ structure_standard: "docs/architecture/structure-standard.md"
139
+ adr_dir: "docs/architecture/adr"
95
140
  api_doc: "docs/interfaces/api.md"
96
141
  api_change_log: "docs/interfaces/api-change-log.md"
97
142
  regression_matrix: "docs/testing/regression-matrix.md"
@@ -130,6 +175,10 @@ docs:
130
175
  - `workflow.mode`:`dev` 或 `verify`,默认推荐 `dev`
131
176
  - `commands.gate_changed` / `commands.gate_standard` / `commands.gate_full`:推荐配置分层门禁命令;旧项目也可以继续只配置 `commands.light_gate`
132
177
  - `gate.*`:按项目声明路径规则和高风险升级规则;未配置时保持标准门禁行为
178
+ - `commands.structure_check`:可覆盖内置结构检查;留空时使用通用 `ap.py structure-check`
179
+ - `structure.*`:通用工程结构阈值、允许的大文件模式、复用搜索目录
180
+ - `optimization.*`:健康基线感知的优化闭环口径,避免重复把已接受债务判定为当前未完成
181
+ - `docs.health_baseline` / `docs.optimization_backlog` / `docs.structure_standard` / `docs.adr_dir`:项目结构治理文档位置
133
182
  - `target_env.*`:目标环境前端 / 后端地址、用户名、密码引用,必须全部填写且真实可用
134
183
  - `jenkins.*`:Jenkins UI/API 用户名、密码引用、Job、分支、镜像、部署环境,必须全部填写且真实可用
135
184
 
@@ -169,6 +218,12 @@ docs:
169
218
  按需填写:
170
219
  - `gate.default_scope`:默认 `standard`;需要小步快跑时设为 `auto` 或 `changed`
171
220
  - `gate.rules`:项目自定义路径规则。每条规则可包含 `name`、`paths`、`commands`、`scope`
221
+ - `structure.enabled`:是否把结构检查纳入 `light-gate`
222
+ - `structure.max_file_lines_warn` / `structure.max_file_lines_block`:文件长度预警 / 阻塞阈值
223
+ - `structure.max_added_lines_to_large_file`:禁止在已偏大的文件里继续大块堆职责
224
+ - `structure.allow_large_files`:生成物、供应商代码、构建产物等允许超长或跳过结构检查的路径
225
+ - `structure.accepted_debt_paths`:已记录为接受债务的历史大文件;只豁免历史体量,不豁免继续大幅新增
226
+ - `optimization.completion_policy`:默认 `baseline-aware`,表示“优化完成”按本轮范围和已记录基线判断,不等于仓库没有任何可优化点
172
227
  - `runtime.*`:仅在本地运行诊断时使用
173
228
  - `commands.build` / `commands.test` / `commands.quick_test` / `commands.lint` / `commands.typecheck` / `commands.format`:按项目实际情况保留
174
229
 
@@ -269,6 +324,36 @@ docs:
269
324
 
270
325
  ---
271
326
 
327
+ ## 1.7 工程结构与优化标准
328
+
329
+ 默认采用 `docs/architecture/structure-standard.md` 中的通用结构标准。具体项目可以按技术栈细化目录名,但不得降低以下要求:
330
+
331
+ 1) 分层清晰
332
+ - 业务规则、用例编排、外部适配、接口入口、共享工具必须有清晰边界。
333
+ - 新代码先落到对应层;没有合适位置时,先补最小设计或 ADR,再新增目录 / 模块。
334
+
335
+ 2) 复用优先
336
+ - 新增工具、并发控制、缓存、请求封装、格式转换、权限判断、校验逻辑前,必须先搜索已有 helper、库、组件、脚本。
337
+ - 正常情况下复用成熟库或项目既有工具;只有明确的性能、并发、部署、许可证、兼容性约束才允许自研,并记录理由和验证。
338
+
339
+ 3) 单文件容量控制
340
+ - 超过 `structure.max_file_lines_warn` 的文件只允许小修和缺陷修复,新增职责应优先抽取模块。
341
+ - 超过 `structure.max_file_lines_block` 的文件不得继续承载新职责,除非该文件在 `structure.allow_large_files` 中声明为生成物或外部产物。
342
+ - 已记录为接受债务的历史大文件可放入 `structure.accepted_debt_paths`,但继续大幅新增仍会被阻塞。
343
+ - 对已偏大的文件一次性增加超过 `structure.max_added_lines_to_large_file` 行时,`structure-check` 会阻塞,要求拆分或写明例外理由。
344
+
345
+ 4) 优化完成标准
346
+ - “优化完成”不表示仓库没有任何可优化点。
347
+ - 默认定义为:本轮约定范围内的 P0/P1/P2 scoped items 已闭环,本地 gate 通过,没有新增未分级 P0/P1,剩余 P2/P3 已进入 backlog 或被接受为债务。
348
+ - 新会话做整体分析时,必须先读 `docs/reviews/project-health-baseline.md` 和 `docs/reviews/optimization-backlog.md`,只报告新增、恶化、未记录 P0/P1,或已记录但需要升级优先级的问题。
349
+
350
+ 5) 本地执行
351
+ - 小步快跑默认执行:`python3 docs/tools/autopipeline/ap.py structure-check --scope auto`
352
+ - 发布、跨模块重构、架构调整默认执行:`python3 docs/tools/autopipeline/ap.py structure-check --scope full`
353
+ - `light-gate` 在 `structure.enabled: true` 时会自动纳入结构检查;如项目需要更强规则,可配置 `commands.structure_check` 覆盖内置实现。
354
+
355
+ ---
356
+
272
357
  ## 2. 标准流程(默认)
273
358
 
274
359
  ### 2.1 开发模式:`workflow.mode: "dev"`
@@ -1,5 +1,8 @@
1
1
  Follow `docs/ENGINEERING.md` strictly. Source of truth: `docs/ENGINEERING.md`.
2
+ Before code changes, read the configured structure standard and place new code in the correct layer; do not add new responsibilities to already-large files.
3
+ Before optimization reviews, read the project health baseline and optimization backlog, and report only new, worsened, unrecorded P0/P1, or upgraded-priority items.
2
4
  Route work through already available MCP servers, installed skills, plugins, and app connectors when they provide current docs, design context, browser evidence, GitHub/CI state, security review, or artifact rendering.
3
5
  Use the `.agents/agents` role model when available: explorer, docs_researcher, browser_debugger, fixer, reviewer. If the client cannot run subagents, execute the same roles sequentially in the main agent.
4
- Default to the lightweight local gate first, then use Jenkins build verification and real target-environment verification as the primary completion gate.
6
+ Default to the lightweight local gate first; when `structure.enabled` is true, the gate includes `structure-check`.
7
+ Use Jenkins build verification and real target-environment verification as the primary completion gate in verify mode.
5
8
  Local Docker Compose and full local regression are on-demand diagnostic tools, not the default gate for every small change.
@@ -1,5 +1,8 @@
1
1
  Follow `docs/ENGINEERING.md` strictly. Source of truth: `docs/ENGINEERING.md`.
2
+ Before code changes, read the configured structure standard and place new code in the correct layer; do not add new responsibilities to already-large files.
3
+ Before optimization reviews, read the project health baseline and optimization backlog, and report only new, worsened, unrecorded P0/P1, or upgraded-priority items.
2
4
  Route work through already available MCP servers, installed skills, plugins, and app connectors when they provide current docs, design context, browser evidence, GitHub/CI state, security review, or artifact rendering.
3
5
  Use the `.agents/agents` role model when available: explorer, docs_researcher, browser_debugger, fixer, reviewer. If the client cannot run subagents, execute the same roles sequentially in the main agent.
4
- Default to the lightweight local gate first, then use Jenkins build verification and real target-environment verification as the primary completion gate.
6
+ Default to the lightweight local gate first; when `structure.enabled` is true, the gate includes `structure-check`.
7
+ Use Jenkins build verification and real target-environment verification as the primary completion gate in verify mode.
5
8
  Local Docker Compose and full local regression are on-demand diagnostic tools, not the default gate for every small change.
@@ -0,0 +1,38 @@
1
+ # ADR-0000 — <Decision Title>
2
+
3
+ - Status: Proposed | Accepted | Superseded
4
+ - Date: YYYY-MM-DD
5
+ - Owner: <name / team>
6
+ - Related task: <task id / link>
7
+
8
+ ## 1. Context
9
+
10
+ What problem or structural pressure requires an architectural decision?
11
+
12
+ ## 2. Decision
13
+
14
+ What decision is being made? Keep it specific and actionable.
15
+
16
+ ## 3. Alternatives Considered
17
+
18
+ | Option | Pros | Cons | Reason not selected |
19
+ | --- | --- | --- | --- |
20
+ | A | | | |
21
+ | B | | | |
22
+
23
+ ## 4. Consequences
24
+
25
+ - Positive:
26
+ - Negative / tradeoffs:
27
+ - Migration impact:
28
+ - Compatibility impact:
29
+
30
+ ## 5. Validation
31
+
32
+ - Tests:
33
+ - Gate:
34
+ - Runtime / benchmark / security evidence:
35
+
36
+ ## 6. Rollback
37
+
38
+ How can this decision be reverted or superseded if it proves wrong?
@@ -0,0 +1,67 @@
1
+ # Project Structure Standard
2
+
3
+ > 通用工程结构标准。项目可以按技术栈调整目录名,但不能降低分层、复用、可维护性和验证要求。
4
+
5
+ ## 1. 目标
6
+
7
+ - 目录结构能表达业务边界、技术边界和变更边界。
8
+ - 单个文件、类、组件、函数只承担清晰职责。
9
+ - 新代码优先复用成熟库、项目已有 helper、组件、脚本和平台能力。
10
+ - 优化结论按健康基线和 backlog 判断,避免反复把已接受债务当成当前阻塞。
11
+
12
+ ## 2. 推荐分层
13
+
14
+ 不同语言和框架可以使用不同目录名,但职责应保持一致:
15
+
16
+ | 层级 | 常见目录名 | 职责 | 不应包含 |
17
+ | --- | --- | --- | --- |
18
+ | Domain | `domain`, `model`, `entity`, `value-object`, `policy` | 业务概念、规则、不可变约束 | HTTP、DB、UI、第三方 SDK 细节 |
19
+ | Application | `application`, `service`, `usecase`, `workflow` | 用例编排、事务边界、跨领域协调 | 控制器入参解析、SQL 细节、组件渲染 |
20
+ | Infrastructure | `infrastructure`, `adapter`, `repository`, `client`, `gateway` | DB、缓存、消息、外部 API、文件系统、运行时适配 | 核心业务规则 |
21
+ | Interface | `api`, `controller`, `handler`, `route`, `page`, `component`, `view` | HTTP/CLI/UI 入口、协议转换、展示逻辑 | 复杂业务编排和持久化细节 |
22
+ | Shared | `shared`, `common`, `utils`, `lib` | 稳定通用工具、类型、组件 | 业务专属逻辑、临时拼凑函数 |
23
+ | Tooling | `scripts`, `tools`, `docs/tools` | 自动化脚本、门禁、迁移辅助 | 在线业务运行逻辑 |
24
+
25
+ ## 3. 落位规则
26
+
27
+ - 修改前先定位现有同类实现、模块边界、调用链和测试入口。
28
+ - 新增业务规则优先进入 Domain 或 Application,不直接塞进 Controller/Page/Component。
29
+ - 新增外部依赖访问优先进入 Infrastructure,并通过接口或窄适配暴露给 Application。
30
+ - UI 组件应拆分为容器、状态/数据适配、纯展示组件;不要在单个页面里混合远程请求、权限、复杂计算和大段渲染。
31
+ - 跨模块、跨层、数据库、API、部署、权限、并发、缓存、核心页面流的变更,需要最小设计;影响长期结构的决策需要 ADR。
32
+
33
+ ## 4. 文件和函数规模
34
+
35
+ 默认阈值来自 `docs/ENGINEERING.md`:
36
+
37
+ - 文件超过 `structure.max_file_lines_warn`:只允许小修、缺陷修复、类型补充;新增职责应先抽取模块。
38
+ - 文件超过 `structure.max_file_lines_block`:不得继续承载新职责,除非是生成物、外部产物或已在 `structure.allow_large_files` 中声明。
39
+ - 历史大文件如果已进入健康基线 / backlog,可在 `structure.accepted_debt_paths` 中登记;登记只豁免历史体量,不豁免继续大幅新增。
40
+ - 函数 / 方法 / 组件超过 `structure.max_function_lines_warn`:应拆分为命名清晰的子函数、hook、service、query、mapper 或 view component。
41
+ - 对大文件新增超过 `structure.max_added_lines_to_large_file` 行:默认阻塞,必须拆分或记录例外理由。
42
+
43
+ ## 5. 复用优先规则
44
+
45
+ 新增以下能力前必须先搜索现有实现:
46
+
47
+ - HTTP/API client、认证、权限、表单校验、错误处理、日志、缓存、重试、并发控制。
48
+ - 日期、金额、单位、国际化、文件处理、导入导出、分页、排序、过滤、权限判断。
49
+ - UI 基础组件、布局、表格、弹窗、上传、图表、状态管理、路由守卫。
50
+ - 自动化脚本、部署脚本、测试工具、mock、fixture、数据迁移 helper。
51
+
52
+ 允许自研的前提:
53
+
54
+ - 成熟库不能满足性能、并发、部署、许可证、离线、兼容性或安全边界。
55
+ - ADR 或设计记录说明取舍。
56
+ - 有测试、benchmark、压测或真实运行证据支撑。
57
+
58
+ ## 6. Review 口径
59
+
60
+ 结构 review 不应只说“还能优化”。必须分级:
61
+
62
+ - P0 阻塞:构建 / 发布 / 数据 / 安全 / 核心流程风险。
63
+ - P1 必修:明显架构违规、契约漂移、重要测试缺失、近期高风险改动。
64
+ - P2 计划债务:大文件、热点目录、可拆分模块、测试增强。
65
+ - P3 可选建议:命名、风格、进一步抽象、审美类优化。
66
+
67
+ “优化完成”只表示当前约定范围闭环,不表示没有任何后续可优化点。新会话必须先读健康基线和 backlog,只报告新增、恶化、未记录 P0/P1,或需要升级优先级的已记录问题。
@@ -8,10 +8,16 @@
8
8
  ## 2. 范围与非目标
9
9
  ## 3. 现状与问题
10
10
  ## 4. 方案与取舍
11
- ## 5. 接口设计(与 docs/interfaces/api.md 对齐)
12
- ## 6. 数据设计(迁移/回滚)
11
+ ## 5. 架构落位与复用检查
12
+ - 目标层级:Domain / Application / Infrastructure / Interface / Shared / Tooling
13
+ - 既有复用点:
14
+ - 是否需要 ADR:Yes / No;如 Yes,记录到 `docs/architecture/adr/`
15
+ - 是否触及大文件 / 大组件:
13
16
 
14
- ## 7. 时序图(强制)
17
+ ## 6. 接口设计(与 docs/interfaces/api.md 对齐)
18
+ ## 7. 数据设计(迁移/回滚)
19
+
20
+ ## 8. 时序图(强制)
15
21
  ```mermaid
16
22
  sequenceDiagram
17
23
  participant C as Client
@@ -26,7 +32,7 @@ sequenceDiagram
26
32
  A-->>C: response
27
33
  ```
28
34
 
29
- ## 8. ER 图(强制)
35
+ ## 9. ER 图(强制)
30
36
  ```mermaid
31
37
  erDiagram
32
38
  ENTITY_A ||--o{ ENTITY_B : relates
@@ -34,10 +40,10 @@ erDiagram
34
40
  ENTITY_B { string id string a_id }
35
41
  ```
36
42
 
37
- ## 9. 接口时序/调用编排(强制)
38
- ## 10. 测试方案(必须自动化 + 覆盖历史 bug)
39
- ## 11. 安全与合规
40
- ## 12. 性能与容量
41
- ## 13. 风险清单
42
- ## 14. 回滚方案
43
- ## 15. 影响面与发布计划
43
+ ## 10. 接口时序/调用编排(强制)
44
+ ## 11. 测试方案(必须自动化 + 覆盖历史 bug)
45
+ ## 12. 安全与合规
46
+ ## 13. 性能与容量
47
+ ## 14. 风险清单
48
+ ## 15. 回滚方案
49
+ ## 16. 影响面与发布计划
@@ -3,22 +3,32 @@
3
3
  > 仅在任务需要独立 review 记录时使用;不是每个小改动的默认强制文档。
4
4
 
5
5
  ## 1. 静态分析结果
6
- - Command:light_gate / diff_check / verify_api_docs / verify_jenkins
6
+ - Command:structure-check / light_gate / diff_check / verify_api_docs / verify_jenkins
7
7
  - Summary:
8
8
  - Issues:
9
9
 
10
- ## 2. 本地轻量校验
10
+ ## 2. 结构与优化基线
11
+ - Structure standard:`docs/architecture/structure-standard.md`
12
+ - Health baseline read:Yes / No / N/A
13
+ - Optimization backlog read:Yes / No / N/A
14
+ - New / worsened issues:
15
+ - Accepted debt not repeated:
16
+ - Completion standard:Met / Not met / N/A
17
+
18
+ ## 3. 本地轻量校验
11
19
  - light_gate or quick_test/test/build:
20
+ - structure-check:
12
21
  - api docs:
13
22
  - jenkins:
14
23
 
15
- ## 3. 按需本地运行验证(如果有)
24
+ ## 4. 按需本地运行验证(如果有)
16
25
  - runtime-up / health:
17
26
 
18
- ## 4. Jenkins 与目标环境
27
+ ## 5. Jenkins 与目标环境
19
28
  - Jenkins readiness:
20
29
  - Target env verification:
21
30
 
22
- ## 5. 风险与结论
31
+ ## 6. 风险与结论
23
32
  - Risk:
24
- - Conclusion:Pass / Blocked
33
+ - Priority:P0 / P1 / P2 / P3 / N/A
34
+ - Conclusion:Pass / Blocked / Accepted debt
@@ -0,0 +1,24 @@
1
+ # Optimization Backlog
2
+
3
+ > 这里记录持续优化项。被记录为 `accepted-debt` 的项目不等于当前任务未完成;只有新增、恶化或升级优先级时才需要重新报告。
4
+
5
+ ## Status Values
6
+
7
+ - `open`: 已确认,等待排期。
8
+ - `accepted-debt`: 当前接受的债务,按触发条件再处理。
9
+ - `in-progress`: 正在处理。
10
+ - `closed`: 已闭环,证据写在表格中。
11
+ - `superseded`: 被其他方案或任务替代。
12
+
13
+ ## Backlog
14
+
15
+ | ID | Priority | Status | Scope | Item | Reason | Acceptance | Last reviewed |
16
+ | --- | --- | --- | --- | --- | --- | --- | --- |
17
+ | OPT-000 | P2 | open | `<path/module>` | | | | YYYY-MM-DD |
18
+
19
+ ## Review Rules
20
+
21
+ - P0/P1 不能长期停留在 backlog;应进入当前迭代或明确升级。
22
+ - P2 可以排队,但必须有范围、原因和验收标准。
23
+ - P3 只在低成本或同域修改时顺手处理,不影响“优化完成”结论。
24
+ - 新会话整体分析只允许新增、升级或关闭条目,不要重复制造同义优化项。
@@ -0,0 +1,63 @@
1
+ # Project Health Baseline
2
+
3
+ > 用于固定“当前项目结构是否达标”的判断口径。整体分析、结构优化和新会话复盘必须先读本文件,再读 `docs/reviews/optimization-backlog.md`。
4
+
5
+ - Baseline date: YYYY-MM-DD
6
+ - Baseline commit: `<git-sha>`
7
+ - Owner: <name / team>
8
+ - Review scope: <repo / module / subsystem>
9
+ - Standard: `docs/architecture/structure-standard.md`
10
+
11
+ ## 1. Current Accepted Structure
12
+
13
+ 记录当前被接受的目录结构、主要模块边界、已知历史原因和不再重复争论的事实。
14
+
15
+ | Area | Current state | Accepted because | Review date |
16
+ | --- | --- | --- | --- |
17
+ | <module/path> | | | |
18
+
19
+ ## 2. Closed Optimization Scope
20
+
21
+ 记录已经闭环的优化项。新会话不能把这些项重复判定为“当前未完成”。
22
+
23
+ | ID | Closed date | Scope | Acceptance evidence |
24
+ | --- | --- | --- | --- |
25
+ | OPT-000 | YYYY-MM-DD | | |
26
+
27
+ ## 3. Accepted Debt
28
+
29
+ 这些是已知但暂不处理的问题。除非新增风险、影响扩大或优先级升级,否则只保留在 backlog,不作为当前任务失败原因。
30
+
31
+ | ID | Priority | Scope | Debt | Why accepted | Revisit trigger |
32
+ | --- | --- | --- | --- | --- | --- |
33
+ | DEBT-000 | P2 | | | | |
34
+
35
+ ## 4. Priority Rules
36
+
37
+ - P0: blocks build, release, deploy, core user flow, data integrity, security, or compliance.
38
+ - P1: clear architectural violation, contract drift, missing test around high-risk change, or recently introduced maintainability risk.
39
+ - P2: planned debt such as large files, hot directories, module extraction, stronger tests, or tool consolidation.
40
+ - P3: optional naming, style, polish, or further abstraction.
41
+
42
+ ## 5. Completion Standard
43
+
44
+ An optimization task is complete when all are true:
45
+
46
+ - The scoped P0/P1/P2 items listed for this task are closed.
47
+ - Local gate passed, including structure check when enabled.
48
+ - No new unclassified P0/P1 was introduced.
49
+ - Remaining P2/P3 items are either in `docs/reviews/optimization-backlog.md` or accepted debt above.
50
+ - Review output says explicitly whether the project meets this baseline.
51
+
52
+ ## 6. New Review Instructions
53
+
54
+ When asked to analyze structure or optimization:
55
+
56
+ - Read this baseline first.
57
+ - Read `docs/reviews/optimization-backlog.md` second.
58
+ - Report only:
59
+ - new or worsened issues;
60
+ - unrecorded P0/P1;
61
+ - backlog items whose priority should now be upgraded;
62
+ - baseline drift.
63
+ - Do not repeat accepted debt as fresh findings.
@@ -15,6 +15,7 @@
15
15
  - Jenkins Build: <build url>
16
16
  - Target Env: <env name / health url / page path>
17
17
  - Verification: <health / key api / key page / business path>
18
+ - Structure Check: <passed / blocked / skipped with reason>
18
19
  - Result: DEV-CLOSED / PASS / FAIL / PARTIAL
19
20
  - Follow-up: <none or todo>
20
21
  - Jenkins Failure: <optional>
@@ -20,6 +20,7 @@
20
20
 
21
21
  ## 3. 质量证据
22
22
  - 本地轻量校验:light_gate or quick_test/test/build / api docs / jenkins / diff-check
23
+ - 结构检查:structure-check
23
24
  - Jenkins Build:
24
25
  - 目标环境验证:
25
26
  - 闭环记录:`docs/tasks/closure-log.md`
@@ -15,6 +15,9 @@
15
15
  - 是否高风险(Yes/No):
16
16
  - 高风险分类(如有):DB / Auth / Payment / Jenkins / Gateway / Upload / Prod Config
17
17
  - 影响面(API / DB / Jenkins / Page / Config / Deploy):
18
+ - 结构落位(Domain / Application / Infrastructure / Interface / Shared / Tooling / N/A):
19
+ - 复用检查(已有 helper / 组件 / 脚本 / 库):
20
+ - 是否需要 ADR(Yes/No):
18
21
  - 最小设计记录:
19
22
  - 验收标准:
20
23
  - 子任务(如有):
@@ -10,6 +10,7 @@ import datetime as _dt
10
10
  import fnmatch
11
11
  import json
12
12
  import os
13
+ import re
13
14
  import time
14
15
  import urllib.parse
15
16
  import urllib.error
@@ -468,6 +469,7 @@ def cmd_gen_summary(args: argparse.Namespace) -> None:
468
469
 
469
470
  ## 4. 质量证据
470
471
  - 本地轻量校验:light_gate or quick_test/test/build / api docs / jenkins / diff-check — TODO
472
+ - 结构检查:structure-check — TODO
471
473
  - Jenkins Build:TODO
472
474
  - 目标环境验证:TODO
473
475
  - 闭环记录:TODO
@@ -935,6 +937,362 @@ def _run_git_diff_check(repo: Path, cfg: dict) -> None:
935
937
  print("[diff-check] OK")
936
938
 
937
939
 
940
+ _DEFAULT_STRUCTURE_ALLOW_PATTERNS = [
941
+ ".git/**",
942
+ ".agents/skills/**",
943
+ ".claude/skills/**",
944
+ ".next/**",
945
+ ".nuxt/**",
946
+ ".svelte-kit/**",
947
+ ".turbo/**",
948
+ "coverage/**",
949
+ "dist/**",
950
+ "build/**",
951
+ "out/**",
952
+ "target/**",
953
+ "vendor/**",
954
+ "node_modules/**",
955
+ "generated/**",
956
+ "**/generated/**",
957
+ "**/__generated__/**",
958
+ "docs/tools/autopipeline/**",
959
+ "**/*.generated.*",
960
+ "**/*.gen.*",
961
+ "**/*.min.js",
962
+ "**/*.bundle.js",
963
+ "**/*.map",
964
+ "package-lock.json",
965
+ "pnpm-lock.yaml",
966
+ "yarn.lock",
967
+ "bun.lockb",
968
+ "go.sum",
969
+ "Cargo.lock",
970
+ ]
971
+ _TEXT_SOURCE_EXTENSIONS = {
972
+ ".bash",
973
+ ".c",
974
+ ".cc",
975
+ ".cfg",
976
+ ".conf",
977
+ ".cpp",
978
+ ".cs",
979
+ ".css",
980
+ ".go",
981
+ ".gradle",
982
+ ".graphql",
983
+ ".h",
984
+ ".hpp",
985
+ ".html",
986
+ ".java",
987
+ ".js",
988
+ ".json",
989
+ ".jsx",
990
+ ".kt",
991
+ ".kts",
992
+ ".less",
993
+ ".m",
994
+ ".md",
995
+ ".mm",
996
+ ".php",
997
+ ".properties",
998
+ ".py",
999
+ ".rb",
1000
+ ".rs",
1001
+ ".scala",
1002
+ ".scss",
1003
+ ".sh",
1004
+ ".sql",
1005
+ ".swift",
1006
+ ".toml",
1007
+ ".ts",
1008
+ ".tsx",
1009
+ ".vue",
1010
+ ".xml",
1011
+ ".yaml",
1012
+ ".yml",
1013
+ ".zsh",
1014
+ }
1015
+ _TEXT_SOURCE_FILENAMES = {
1016
+ "Dockerfile",
1017
+ "Jenkinsfile",
1018
+ "Makefile",
1019
+ "go.mod",
1020
+ "package.json",
1021
+ "requirements.txt",
1022
+ "pyproject.toml",
1023
+ "tsconfig.json",
1024
+ }
1025
+ _FUNCTION_START_RE = re.compile(
1026
+ r"^\s*(?:export\s+)?(?:async\s+)?(?:def|function|func)\s+[A-Za-z_][\w]*\b"
1027
+ r"|^\s*(?:public|private|protected|static|final|async|\s)+\s*[\w<>\[\], ?]+\s+[A-Za-z_]\w*\s*\([^;]*\)\s*\{"
1028
+ r"|^\s*(?:export\s+)?(?:const|let|var)\s+[A-Za-z_]\w*\s*=\s*(?:async\s*)?\([^)]*\)\s*=>"
1029
+ )
1030
+
1031
+
1032
+ def _structure_cfg(cfg: dict) -> dict:
1033
+ value = cfg.get("structure") or {}
1034
+ return value if isinstance(value, dict) else {}
1035
+
1036
+
1037
+ def _optimization_cfg(cfg: dict) -> dict:
1038
+ value = cfg.get("optimization") or {}
1039
+ return value if isinstance(value, dict) else {}
1040
+
1041
+
1042
+ def _bool_config(value: object, default: bool = False) -> bool:
1043
+ if value is None:
1044
+ return default
1045
+ if isinstance(value, bool):
1046
+ return value
1047
+ raw = _text(value).lower()
1048
+ if not raw:
1049
+ return default
1050
+ if raw in {"1", "true", "yes", "on"}:
1051
+ return True
1052
+ if raw in {"0", "false", "no", "off"}:
1053
+ return False
1054
+ return default
1055
+
1056
+
1057
+ def _int_config(value: object, default: int) -> int:
1058
+ try:
1059
+ return int(value)
1060
+ except Exception:
1061
+ return default
1062
+
1063
+
1064
+ def _tracked_files(repo: Path) -> list[str]:
1065
+ return _unique_paths(_git_lines(repo, ["git", "ls-files"]))
1066
+
1067
+
1068
+ def _structure_allow_patterns(structure_cfg: dict) -> list:
1069
+ patterns = list(_DEFAULT_STRUCTURE_ALLOW_PATTERNS)
1070
+ patterns.extend(_as_list(structure_cfg.get("allow_large_files")))
1071
+ patterns.extend(_as_list(structure_cfg.get("exclude")))
1072
+ return patterns
1073
+
1074
+
1075
+ def _structure_accepted_debt_patterns(structure_cfg: dict) -> list:
1076
+ return _as_list(structure_cfg.get("accepted_debt_paths"))
1077
+
1078
+
1079
+ def _is_structure_accepted_debt(path: str, structure_cfg: dict) -> bool:
1080
+ return _path_matches(path, _structure_accepted_debt_patterns(structure_cfg))
1081
+
1082
+
1083
+ def _is_structure_candidate(path: str, structure_cfg: dict) -> bool:
1084
+ normalized = path.replace("\\", "/").lstrip("./")
1085
+ if _path_matches(normalized, _structure_allow_patterns(structure_cfg)):
1086
+ return False
1087
+ name = Path(normalized).name
1088
+ suffix = Path(normalized).suffix.lower()
1089
+ return suffix in _TEXT_SOURCE_EXTENSIONS or name in _TEXT_SOURCE_FILENAMES
1090
+
1091
+
1092
+ def _structure_paths_for_scope(repo: Path, scope: str, base_ref: str, structure_cfg: dict) -> list[str]:
1093
+ if scope == "full":
1094
+ paths = _tracked_files(repo)
1095
+ else:
1096
+ paths = _changed_files(repo, base_ref=base_ref)
1097
+ return [path for path in paths if _is_structure_candidate(path, structure_cfg)]
1098
+
1099
+
1100
+ def _read_text_lines(repo: Path, path: str) -> Optional[list[str]]:
1101
+ file_path = repo / path
1102
+ if not file_path.exists() or not file_path.is_file():
1103
+ return None
1104
+ try:
1105
+ return file_path.read_text(encoding="utf-8").splitlines()
1106
+ except UnicodeDecodeError:
1107
+ return None
1108
+ except OSError:
1109
+ return None
1110
+
1111
+
1112
+ def _parse_numstat_line(line: str) -> tuple[str, int]:
1113
+ parts = line.split("\t", 2)
1114
+ if len(parts) < 3:
1115
+ return "", 0
1116
+ added_raw, _, path = parts
1117
+ if added_raw == "-":
1118
+ return "", 0
1119
+ try:
1120
+ added = int(added_raw)
1121
+ except ValueError:
1122
+ return "", 0
1123
+ return path.replace("\\", "/").strip(), added
1124
+
1125
+
1126
+ def _added_lines_by_path(repo: Path, base_ref: str = "") -> dict[str, int]:
1127
+ added: dict[str, int] = {}
1128
+ commands: list[list[str]] = []
1129
+ effective_base = base_ref or _default_base_ref(repo)
1130
+ if effective_base:
1131
+ commands.append(["git", "diff", "--numstat", f"{effective_base}...HEAD"])
1132
+ commands.extend([
1133
+ ["git", "diff", "--numstat"],
1134
+ ["git", "diff", "--cached", "--numstat"],
1135
+ ])
1136
+
1137
+ for cmd in commands:
1138
+ for line in _git_lines(repo, cmd):
1139
+ path, count = _parse_numstat_line(line)
1140
+ if path:
1141
+ added[path] = added.get(path, 0) + count
1142
+
1143
+ for path in _git_lines(repo, ["git", "ls-files", "--others", "--exclude-standard"]):
1144
+ lines = _read_text_lines(repo, path)
1145
+ if lines is not None:
1146
+ added[path] = added.get(path, 0) + len(lines)
1147
+ return added
1148
+
1149
+
1150
+ def _function_size_warnings(path: str, lines: list[str], threshold: int) -> list[str]:
1151
+ if threshold <= 0:
1152
+ return []
1153
+ starts: list[int] = []
1154
+ for index, line in enumerate(lines):
1155
+ if _FUNCTION_START_RE.search(line):
1156
+ starts.append(index)
1157
+ warnings: list[str] = []
1158
+ for pos, start in enumerate(starts):
1159
+ end = starts[pos + 1] if pos + 1 < len(starts) else len(lines)
1160
+ size = end - start
1161
+ if size > threshold:
1162
+ warnings.append(f"{path}:{start + 1} function-like block has {size} lines (warn>{threshold})")
1163
+ return warnings
1164
+
1165
+
1166
+ def _configured_structure_docs(cfg: dict) -> dict[str, str]:
1167
+ docs_cfg = cfg.get("docs") or {}
1168
+ return {
1169
+ "docs.health_baseline": _text(docs_cfg.get("health_baseline")),
1170
+ "docs.optimization_backlog": _text(docs_cfg.get("optimization_backlog")),
1171
+ "docs.structure_standard": _text(docs_cfg.get("structure_standard")),
1172
+ }
1173
+
1174
+
1175
+ def _structure_gate_enabled(cfg: dict) -> bool:
1176
+ if _configured_command(cfg, "structure_check"):
1177
+ return True
1178
+ structure_cfg = cfg.get("structure")
1179
+ if not isinstance(structure_cfg, dict):
1180
+ return False
1181
+ return _bool_config(structure_cfg.get("enabled"), default=True)
1182
+
1183
+
1184
+ def _print_limited(label: str, items: list[str], max_items: int = 60) -> None:
1185
+ if not items:
1186
+ return
1187
+ print(label)
1188
+ for item in items[:max_items]:
1189
+ print(f"- {item}")
1190
+ remaining = len(items) - max_items
1191
+ if remaining > 0:
1192
+ print(f"- ... {remaining} more")
1193
+
1194
+
1195
+ def cmd_structure_check(args: argparse.Namespace) -> None:
1196
+ repo = Path(args.repo).resolve()
1197
+ ensure_git_repo(repo)
1198
+ cfg = _load_cfg(repo)
1199
+ requested_scope = str(getattr(args, "scope", "") or "").strip().lower()
1200
+ impact = _impact_summary(cfg, repo, requested_scope=requested_scope, base_ref=str(getattr(args, "base", "") or ""))
1201
+ selected_scope = str(impact["selected_scope"])
1202
+ base_ref = str(getattr(args, "base", "") or "")
1203
+
1204
+ structure_cfg = _structure_cfg(cfg)
1205
+ optimization_cfg = _optimization_cfg(cfg)
1206
+ warn_file_lines = _int_config(structure_cfg.get("max_file_lines_warn"), 800)
1207
+ block_file_lines = _int_config(structure_cfg.get("max_file_lines_block"), 1500)
1208
+ warn_function_lines = _int_config(structure_cfg.get("max_function_lines_warn"), 120)
1209
+ max_added_to_large = _int_config(structure_cfg.get("max_added_lines_to_large_file"), 80)
1210
+ block_large_growth = _bool_config(structure_cfg.get("block_new_responsibility_in_large_file"), True)
1211
+
1212
+ paths = _structure_paths_for_scope(repo, selected_scope, base_ref, structure_cfg)
1213
+ added_by_path = _added_lines_by_path(repo, base_ref=base_ref) if selected_scope != "full" else {}
1214
+
1215
+ blocking: list[str] = []
1216
+ warnings: list[str] = []
1217
+ inspected = 0
1218
+
1219
+ for path in paths:
1220
+ lines = _read_text_lines(repo, path)
1221
+ if lines is None:
1222
+ continue
1223
+ inspected += 1
1224
+ line_count = len(lines)
1225
+ accepted_debt = _is_structure_accepted_debt(path, structure_cfg)
1226
+ if block_file_lines > 0 and line_count > block_file_lines:
1227
+ message = f"{path} has {line_count} lines (block>{block_file_lines}); split responsibilities before adding more work"
1228
+ if accepted_debt:
1229
+ warnings.append(message + " [accepted_debt_paths]")
1230
+ else:
1231
+ blocking.append(message)
1232
+ elif warn_file_lines > 0 and line_count > warn_file_lines:
1233
+ warnings.append(f"{path} has {line_count} lines (warn>{warn_file_lines}); prefer extraction before extending it")
1234
+
1235
+ added_lines = added_by_path.get(path, 0)
1236
+ if (
1237
+ block_large_growth
1238
+ and selected_scope != "full"
1239
+ and warn_file_lines > 0
1240
+ and max_added_to_large > 0
1241
+ and line_count > warn_file_lines
1242
+ and added_lines > max_added_to_large
1243
+ ):
1244
+ blocking.append(
1245
+ f"{path} adds {added_lines} lines to an already large file ({line_count} lines); "
1246
+ "extract a module/helper or document why this is intentionally co-located"
1247
+ )
1248
+
1249
+ warnings.extend(_function_size_warnings(path, lines, warn_function_lines))
1250
+
1251
+ missing_docs: list[str] = []
1252
+ for key, rel_path in _configured_structure_docs(cfg).items():
1253
+ if rel_path and not Path(repo, rel_path).exists():
1254
+ missing_docs.append(f"{key} missing on disk: {rel_path}")
1255
+ require_baseline = _bool_config(optimization_cfg.get("require_baseline_for_global_review"), True)
1256
+ if missing_docs and selected_scope == "full" and require_baseline:
1257
+ blocking.extend(missing_docs)
1258
+ else:
1259
+ warnings.extend(missing_docs)
1260
+
1261
+ result = {
1262
+ "scope": selected_scope,
1263
+ "inspected_files": inspected,
1264
+ "blocking": blocking,
1265
+ "warnings": warnings,
1266
+ }
1267
+ if getattr(args, "json", False):
1268
+ print(json.dumps(result, ensure_ascii=False, indent=2))
1269
+ else:
1270
+ _print_limited("[structure-check] blocking", blocking)
1271
+ _print_limited("[structure-check] warnings", warnings)
1272
+
1273
+ if blocking:
1274
+ raise APError(f"structure-check failed with {len(blocking)} blocking issue(s)")
1275
+
1276
+ print(f"[structure-check] OK scope={selected_scope} inspected={inspected} warnings={len(warnings)}")
1277
+
1278
+
1279
+ def _run_structure_check_for_gate(repo: Path, cfg: dict, selected_scope: str, base_ref: str) -> list[str]:
1280
+ if not _structure_gate_enabled(cfg):
1281
+ return []
1282
+ if _configured_command(cfg, "structure_check"):
1283
+ _run_configured_command(repo, cfg, "structure_check")
1284
+ return ["structure_check"]
1285
+ cmd_structure_check(
1286
+ argparse.Namespace(
1287
+ repo=str(repo),
1288
+ scope=selected_scope,
1289
+ base=base_ref,
1290
+ json=False,
1291
+ )
1292
+ )
1293
+ return ["structure_check"]
1294
+
1295
+
938
1296
  def cmd_run(args: argparse.Namespace) -> None:
939
1297
  """
940
1298
  Run any configured gate command by name.
@@ -970,13 +1328,15 @@ def cmd_light_gate(args: argparse.Namespace) -> None:
970
1328
  selected_scope = str(impact["selected_scope"])
971
1329
  paths = list(impact.get("changed_files") or [])
972
1330
  matching_rules = _matching_gate_rules(paths, _gate_cfg(cfg))
1331
+ executed: list[str] = []
1332
+ executed.extend(_run_structure_check_for_gate(repo, cfg, selected_scope, str(getattr(args, "base", "") or "")))
973
1333
 
974
1334
  if selected_scope == "changed":
975
- executed = _run_changed_gate(repo, cfg, paths, matching_rules)
1335
+ executed.extend(_run_changed_gate(repo, cfg, paths, matching_rules))
976
1336
  elif selected_scope == "full":
977
- executed = _run_full_gate(repo, cfg)
1337
+ executed.extend(_run_full_gate(repo, cfg))
978
1338
  else:
979
- executed = _run_standard_gate(repo, cfg)
1339
+ executed.extend(_run_standard_gate(repo, cfg))
980
1340
 
981
1341
  _run_git_diff_check(repo, cfg)
982
1342
  cmd_verify_api_docs(argparse.Namespace(repo=str(repo)))
@@ -1367,6 +1727,7 @@ def cmd_record_closure(args: argparse.Namespace) -> None:
1367
1727
  verification_text = "; ".join(verification_items) if verification_items else "TODO"
1368
1728
  follow_up = str(args.follow_up or "").strip() or "none"
1369
1729
  jenkins_build = str(args.jenkins or "").strip() or "TODO"
1730
+ structure_check = str(getattr(args, "structure_check", "") or "").strip() or "TODO"
1370
1731
 
1371
1732
  lines = [
1372
1733
  f"## {task_id} — {title} — {timestamp}",
@@ -1375,6 +1736,7 @@ def cmd_record_closure(args: argparse.Namespace) -> None:
1375
1736
  f"- Jenkins Build: {jenkins_build}",
1376
1737
  f"- Target Env: {target_env}",
1377
1738
  f"- Verification: {verification_text}",
1739
+ f"- Structure Check: {structure_check}",
1378
1740
  f"- Result: {args.result}",
1379
1741
  f"- Follow-up: {follow_up}",
1380
1742
  ]
@@ -1403,6 +1765,7 @@ def _record_commit_push_closure(
1403
1765
  verification: List[str],
1404
1766
  result: str,
1405
1767
  follow_up: str,
1768
+ structure_check: str,
1406
1769
  ) -> None:
1407
1770
  cmd_record_closure(
1408
1771
  argparse.Namespace(
@@ -1415,6 +1778,7 @@ def _record_commit_push_closure(
1415
1778
  verification=verification,
1416
1779
  result=result,
1417
1780
  follow_up=follow_up,
1781
+ structure_check=structure_check,
1418
1782
  initial_commit=args.initial_commit,
1419
1783
  jenkins_failure=args.jenkins_failure,
1420
1784
  fix_commit=args.fix_commit,
@@ -1431,12 +1795,14 @@ def cmd_commit_push(args: argparse.Namespace) -> None:
1431
1795
  target_cfg = (cfg.get("target_env") or {})
1432
1796
 
1433
1797
  msg = args.msg
1798
+ structure_check_status = "skipped"
1434
1799
 
1435
1800
  if args.require_runtime_health:
1436
1801
  cmd_wait_health(argparse.Namespace(repo=str(repo), scope="runtime"))
1437
1802
 
1438
1803
  if mode in {"dev", "verify"} or args.require_light_gate:
1439
1804
  cmd_light_gate(argparse.Namespace(repo=str(repo)))
1805
+ structure_check_status = "passed via light-gate" if _structure_gate_enabled(cfg) else "skipped (structure disabled)"
1440
1806
 
1441
1807
  if args.require_jenkins:
1442
1808
  cmd_verify_jenkins(argparse.Namespace(repo=str(repo)))
@@ -1459,6 +1825,7 @@ def cmd_commit_push(args: argparse.Namespace) -> None:
1459
1825
  verification=dev_verification,
1460
1826
  result=args.result or "DEV-CLOSED",
1461
1827
  follow_up=args.follow_up or "Run verify mode when Jenkins and target-environment evidence is required.",
1828
+ structure_check=args.structure_check or structure_check_status,
1462
1829
  )
1463
1830
 
1464
1831
  run(["git", "add", "-A"], cwd=repo)
@@ -1509,6 +1876,7 @@ def cmd_commit_push(args: argparse.Namespace) -> None:
1509
1876
  verification=verification,
1510
1877
  result=args.result or "PASS",
1511
1878
  follow_up=args.follow_up or "none",
1879
+ structure_check=args.structure_check or structure_check_status,
1512
1880
  )
1513
1881
  run(["git", "add", "-A"], cwd=repo)
1514
1882
  closure_diff = run(["git", "diff", "--cached", "--name-only"], cwd=repo).stdout.strip()
@@ -1525,6 +1893,7 @@ def cmd_commit_push(args: argparse.Namespace) -> None:
1525
1893
  verification=args.verification or [],
1526
1894
  result=args.result or "PARTIAL",
1527
1895
  follow_up=args.follow_up or "none",
1896
+ structure_check=args.structure_check or structure_check_status,
1528
1897
  )
1529
1898
  print(f"[commit-push] OK - mode={mode}")
1530
1899
 
@@ -1557,6 +1926,12 @@ def main(argv: Optional[List[str]] = None) -> int:
1557
1926
  s.add_argument("--json", action="store_true")
1558
1927
  s.set_defaults(func=cmd_impact)
1559
1928
 
1929
+ s = sp.add_parser("structure-check")
1930
+ s.add_argument("--scope", choices=sorted(_GATE_SCOPES), default="")
1931
+ s.add_argument("--base")
1932
+ s.add_argument("--json", action="store_true")
1933
+ s.set_defaults(func=cmd_structure_check)
1934
+
1560
1935
  s = sp.add_parser("light-gate")
1561
1936
  s.add_argument("--scope", choices=sorted(_GATE_SCOPES), default="")
1562
1937
  s.add_argument("--base")
@@ -1609,6 +1984,7 @@ def main(argv: Optional[List[str]] = None) -> int:
1609
1984
  s.add_argument("--jenkins")
1610
1985
  s.add_argument("--target-env")
1611
1986
  s.add_argument("--verification", action="append")
1987
+ s.add_argument("--structure-check")
1612
1988
  s.add_argument("--result", choices=["DEV-CLOSED", "PASS", "FAIL", "PARTIAL"], required=True)
1613
1989
  s.add_argument("--follow-up")
1614
1990
  s.add_argument("--initial-commit")
@@ -1642,6 +2018,7 @@ def main(argv: Optional[List[str]] = None) -> int:
1642
2018
  s.add_argument("--jenkins-build")
1643
2019
  s.add_argument("--target-env")
1644
2020
  s.add_argument("--verification", action="append")
2021
+ s.add_argument("--structure-check")
1645
2022
  s.add_argument("--result", choices=["DEV-CLOSED", "PASS", "FAIL", "PARTIAL"])
1646
2023
  s.add_argument("--follow-up")
1647
2024
  s.add_argument("--initial-commit")
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@elvis1513/auto-coding-skill",
3
- "version": "2.0.4",
3
+ "version": "2.0.5",
4
4
  "description": "CLI installer for auto-coding-skill (Claude Code + Codex CLI) with Go fullstack + Jenkins workflow support.",
5
5
  "type": "module",
6
6
  "bin": {