メニュー
Quantitative design audit. Counts pass-throughs, duplication, doc gaps, naming issues, and exceptions across 5 dimensions, scored 0-4.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
SOC 職業分類に基づく
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/mhenke/john-ousterhout-skills --skill aposd-auditコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SKILL.md を表示中
Qualitative design review. Two independent personas evaluate your code against 18 APOSD principles and flag top issues by severity.
Always-on design rules for AI coding agents. 15 principles from A Philosophy of Software Design — applies to every task without explicit invocation.
Use when creating a new release — drafting a changelog entry, creating git tags, publishing via GitHub Releases, or updating README install examples to pin to the latest tagged version.
| name | aposd-audit |
| description | Quantitative design audit. Counts pass-throughs, duplication, doc gaps, naming issues, and exceptions across 5 dimensions, scored 0-4. |
| keywords | ["design","audit","aposd","refactoring","code-quality","static-analysis"] |
| scope_max_input | unlimited |
| scope_max_output | unlimited |
| scope_analysis_depth | quantitative |
| version | 1.0.0 |
| author | wshobson |
| license | MIT |
Run systematic design quality checks and generate a comprehensive report. Don't fix issues; document them for review.
This is a code-level design audit — check what's measurable and verifiable in the implementation. Every dimension is scored by counting concrete, observable constructs. Fix the count → score goes up, every time.
Follows the impeccable audit convention: measure what's objectively countable, not what's interpretive.
Scoring rubric: Score each dimension 0-4. Total /20. Rating bands: 18-20 Excellent, 14-17 Good, 10-13 Acceptable, 6-9 Poor, 0-5 Critical.
aposd audit src/ # audit a directory
aposd audit src/services/order-service.js # audit a single file
aposd audit # defaults to workspace root
The report is printed to stdout.
This skill audits a single codebase target per invocation. It measures 5 design dimensions by counting observable constructs — pass-throughs, duplication, documentation gaps, naming issues, and exception patterns. It does not evaluate functional correctness, runtime performance, or test coverage. Each dimension is scored 0-4 from concrete evidence only.
What this skill does NOT cover:
Resolve the target to a concrete file path, directory, or module name. If no target is specified, default to the current workspace root directory.
Full scan: Scan all files in the target — no sampling. For large targets (>50 files), use sub-agents to parallelize the scan across directory groups.
| Dimension | Counts | Score 0-4 |
|---|
| Pass-Through Proliferation | Pass-through methods + variable chains | 4=0, 3=1-2, 2=3-5, 1=6-10, 0=10+ |
| Information Duplication | Same knowledge in multiple modules | 4=0, 3=1-2, 2=3-4, 1=5-7, 0=8+ |
| Interface Documentation | % of public methods documented | 4=90%+, 3=70-89%, 2=40-69%, 1=10-39%, 0=<10% |
| Naming Quality | Vague names + convention violations | 4=0, 3=1-2, 2=3-5, 1=6-10, 0=10+ |
| Exception Discipline | Custom exceptions + catch-and-rethrow | 4=0 custom, 3=1-2, 2=3-5, 1=6-10, 0=10+ |
aposd critique insteadRun comprehensive checks across 5 dimensions. Score each dimension 0-4 by counting concrete, observable constructs.
Count: Pass-through methods (method body only delegates to another method with the same signature) + pass-through variable chains (context/config threaded through methods that don't use it).
Score 0-4:
Calibration:
getUser() body is exactly return this.db.fetchUser(id)handleClick(e) body is this.onClick(e) with nothing elseprocessData() → transformData() → applyRules() where middle just calls the nextconfig threaded through 5 methods that only pass it to a 6th that uses itreturn this.db.query(normalize(id)))a(x); return b(y))Count: Instances where the same design knowledge (URL paths, schema fields, business rules, configuration keys, magic strings/numbers) appears in multiple independent modules. Count each distinct piece of knowledge that's duplicated.
Score 0-4:
Calibration:
"SELECT * FROM orders WHERE status = 'active'" in user-service.js and order-service.jsMAX_RETRIES = 3 defined in retry.js and again in network-client.js"orders_expire_after_days": 30 in both config schema and validation logicimport React from "react") — that's a dependency, not leakageformatDate() called from multiple modules — that's normal usageCount: Number of public methods/functions without interface comments. Report as both count and percentage of total public methods.
Score 0-4:
Calibration:
// TODO or inline comment, or no comment at all/** Get user */ getUser())Count: Identifiers matching the vague names blocklist — data, info, tmp, handle, process, util, helper, manager, stuff, thing. Also count violations of project naming conventions (inconsistent casing, mixed patterns).
Score 0-4:
Calibration:
data, info, tmp, handle, process, util, helper, manager, stuff, thing used as function names, class names, or variable namescamelCase and snake_case mixed in the same moduleUserService and user_service referring to the same conceptdata as a parameter in a generic utility (e.g., JSON.parse(data)) — context matterstmp in a 3-line test helper scoped to a single functionCount: Custom exception/error classes defined (not standard library types). Count catch blocks that only re-throw, log, or swallow the same exception type.
Score 0-4:
Calibration:
class UserNotFoundError extends Error {} — custom exception classclass PaymentError extends Error { constructor(code, msg) { super(msg); this.code = code; } } — custom with extra fieldstry { ... } catch (e) { throw new ApiError(e.message); } — catch-and-rethrowtry { ... } catch (e) { log(e); throw e; } — log-and-rethrowError, TypeError, RangeError directly — only count custom subclassestry { ... } catch (e) { return defaultValue; } — that's masking, not rethrowingcatch (e) { throw new ApiError(500, e.message); }) — that's proper maskingScore each dimension 0-4. Every score must cite both the rubric criterion and the code evidence:
| # | Dimension | Score | Key Finding | Evidence |
|---|---|---|---|---|
| 1 | Pass-Through Proliferation | ? | Count found | File:line:pattern cited |
| 2 | Information Duplication | ? | Count found | File:line:pattern cited |
| 3 | Interface Documentation | ? | % documented | File:line:pattern cited |
| 4 | Naming Quality | ? | Count found | File:line:pattern cited |
| 5 | Exception Discipline | ? | Count found | File:line:pattern cited |
| Total | ??/20 | [Rating band] |
Assess based on red flag counts found across the 5 dimensions:
Every finding must pass the Specificity Validation Gate. Tag with P0-P3 severity:
For each issue, document:
Identify recurring problems that indicate systemic gaps rather than one-off mistakes:
Note what's working well: dimensions scoring ≥3, clean patterns that prevent complexity. Be objective — explain precisely why they reduce change amplification or cognitive load.
Given a target at src/services/, the audit report would look like:
| # | Dimension | Score | Key Finding |
|---|-----------|-------|-------------|
| 1 | Pass-Through Proliferation | 2 | 4 pass-through methods found (findById→repo.findById, etc.) |
| 2 | Information Duplication | 1 | "expired_at" threshold defined in 3 places |
| 3 | Interface Documentation | 3 | 70% of public methods documented |
| 4 | Naming Quality | 3 | 2 vague names ("data", "helper") |
| 5 | Exception Discipline | 4 | 0 custom exceptions, no catch-and-rethrow |
| **Total** | | **13/20** | **Acceptable** |
**Tactical Tornado Risk:** Medium — pass-through proliferation across service layer is a systemic pattern.
This is illustrative. Your output will follow this structure but reflect the actual target's counts.
See scripts/audit-report-template.md for the standalone template that can be reused programmatically. Copy it and fill in your findings — each ?, __, [ ] placeholder maps to your actual counts.
Before reporting any finding, self-validate:
□ File path (absolute or relative to target)
□ Line number(s)
□ Code pattern (exact snippet, 1-3 lines)
□ Dimension (Pass-Through / Duplication / Documentation / Naming / Exceptions)
□ Count (how many instances)
□ Recommendation (concrete action)
Missing any field → finding is discarded.
No rubber-stamps. A score of 20/20 with no evidence counts per dimension is not a valid audit. Every score must cite the count behind it. If you catch yourself writing a score without evidence, stop and restart the gate check.
Stop-and-return. If you find yourself writing a finding without a file:line:pattern or count, do not continue. Stop. Restart the validation gate for that finding. An unverifiable finding is noise, not signal.
Passing example:
□ File path: src/services/user-service.js
□ Line number(s): 42-48
□ Code pattern: "SELECT * FROM orders WHERE user_id = ?" built inline, same query in order-service.js:87
□ Dimension: Information Duplication
□ Count: 2 instances of the same SQL pattern
□ Recommendation: Extract into OrderRepository.findByUserId(userId)
List recommended actions in priority order (P0 first, then P1, then P2):
After presenting the summary, tell the user:
To fix using APOSD design principles, load the
aposdskill. It applies the 15 APOSD behavioral rules during implementation. Address findings in the priority order above. Each finding is tagged with its affected dimension so you can focus on one area at a time.Re-run
aposd auditafter fixes to see your score improve.
IMPORTANT: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters.
See references/troubleshooting.md for a comprehensive troubleshooting guide covering common problems, recovery procedures, error handling patterns, and edge cases.
See references/troubleshooting.md for common audit mistakes and how to avoid them.
NEVER:
See examples/full-audit-workflow.sh for a copy-paste-ready bash script that runs the complete audit pipeline.
import json, sys
with open(sys.argv[1]) as f:
report = json.load(f)
dimensions = report.get("dimensions", {})
total = sum(d["score"] for d in dimensions.values())
print(f"Design Health Score: {total}/20")
for name, dim in dimensions.items():
grade = "Excellent" if dim["score"] >= 4 else "Good" if dim["score"] >= 3 else "Acceptable" if dim["score"] >= 2 else "Poor"
print(f" {name}: {dim['score']}/4 ({grade}) — {dim['count']} instances at {dim['locations'][0] if dim['locations'] else 'N/A'}")
Copy this script, point it at the JSON output of aposd audit --output json, and it prints a summary.
See examples/example-audit-report.md for a complete, filled-in audit report showing all sections with real findings, severity classifications, and recommendations.