harness-audit

Harness Audit

Automatically scan a codebase for the five most common harness self-deceptions. For each one found, explain what's wrong, why it matters, and offer to fix it.

Framework: Five Self-Deceptions

#	Self-Deception	What you think	What's actually true	Layer
1	The Stale Goal	"I have a goal"	Your goal doc is months old and doesn't match what you're building	L1
2	The Monolith	"I have instructions"	Everything is in one file with no priority structure	L2
3	The Paper Rule	"I have checks"	Your checks are generic defaults, not project-specific constraints	L3
4	The Gut Review	"I review everything"	No systematic quality criteria; review quality varies by how busy you are	L4
5	The Frozen Harness	"I set up my harness"	Nothing harness-related has changed in 30+ days	L4

---

Audit Procedure

Step 1: Identify Domain & Gather Data

Determine project type. Load domain-specific reference if available:

• Software engineering → read docs/software-engineering.md for additional checks
• Other domains → use generic checks below

Run all data gathering commands. Store results — you'll reference them in the diagnosis.

# === Goal documents ===
# Check for goal/spec/PRD files
find docs/ -maxdepth 2 \( -name "PRD*" -o -name "spec*" -o -name "requirements*" -o -name "features*" \) 2>/dev/null
ls README.md docs/PRD.md docs/product-spec.md docs/requirements.md docs/features.md docs/decisions/*.md 2>/dev/null

# Check if instruction file references goal documents
grep -i -E "(goal|objective|spec|prd|requirement|feature|docs/)" CLAUDE.md .cursorrules 2>/dev/null

# Goal freshness: last modified date vs project activity
stat -c '%Y' docs/PRD.md docs/requirements.md docs/features.md 2>/dev/null
git log -1 --format='%at' 2>/dev/null

# === Instruction files ===
# Line count of main instruction file
wc -l CLAUDE.md .cursorrules .github/copilot-instructions.md AGENTS.md 2>/dev/null

# Check for progressive disclosure (links to other docs)
grep -c "\[.*\](.*\.md)" CLAUDE.md 2>/dev/null
grep -c "see \|refer to \|详见\|参考" CLAUDE.md 2>/dev/null

# Check for package/module-level instruction files
find . -name "CLAUDE.md" -not -path "./CLAUDE.md" -not -path "*/node_modules/*" 2>/dev/null

# Count "must/never/always" rules vs total rules
grep -c -i -E "must|never|always|绝对|必须|不得" CLAUDE.md 2>/dev/null
grep -c "^-\|^[0-9]\." CLAUDE.md 2>/dev/null

# === Automated checks ===
# CI/CD
ls .github/workflows/*.yml .gitlab-ci.yml 2>/dev/null

# Pre-commit hooks
ls .husky/pre-commit .git/hooks/pre-commit 2>/dev/null
cat .husky/pre-commit 2>/dev/null

# Custom check scripts (project-specific, not framework defaults)
find scripts/ -name "*harness*" -o -name "*check*" -o -name "*lint*" 2>/dev/null
find . -name "*.arch.*" -o -name "*architecture*test*" -not -path "*/node_modules/*" 2>/dev/null | head -5

# Count custom rules vs framework defaults
# (Read CI config to see if there are project-specific checks beyond standard lint/typecheck)

# === Quality signals ===
ls docs/QUALITY_SCORE.md 2>/dev/null
ls jest.config.* vitest.config.* coverage/ 2>/dev/null

# === Harness evolution ===
# Harness-related commits in last 30 days
git log --since="30 days ago" --oneline -- \
  CLAUDE.md .cursorrules AGENTS.md docs/ scripts/harness-checks.sh \
  .eslintrc* commitlint.config.* .husky/ 2>/dev/null | wc -l

# Total commits for context
echo "Total commits (30d):"
git log --since="30 days ago" --oneline 2>/dev/null | wc -l

# Last modified date of instruction file
git log -1 --format='%ar' -- CLAUDE.md 2>/dev/null