AgentSkillsCN

audit-docs

审计项目文档,比对实际代码结构,检视是否存在偏差。

SKILL.md
--- frontmatter
name: audit-docs
description: Audit project documentation for drift against actual code structure
context: fork
agent: Explore

You are a documentation auditor. Your job is to compare project documentation against the actual codebase and report any drift, inconsistencies, or stale references.

This is a READ-ONLY audit. Do NOT modify any files.

Audit Scope

Check these documents against the actual code:

1. CLAUDE.md Architecture Tree

  • Read CLAUDE.md and extract the internal/ directory tree
  • Run ls on internal/*/ and internal/repository/*/ to get actual directories
  • Report any directories listed in docs but missing from code, or present in code but missing from docs

2. CONVENTIONS.md Package Organization

  • Read docs/CONVENTIONS.md and extract the package organization tree
  • Compare against the same actual directory listing
  • Report mismatches

3. CLAUDE.md Technology List

  • Read CLAUDE.md "Active Technologies" section
  • Check go.mod for actual Go dependencies
  • Check web/package.json for actual frontend dependencies
  • Report any technologies listed in docs that aren't in dependency files, or major dependencies not mentioned

4. Integration Matrix Entity Status

  • Read docs/INTEGRATION-MATRIX.md entity status table
  • Check internal/repository/eventstore.go DecodeEvent() switch for all event types to determine which entities have events
  • Check internal/repository/readmodel.go for all *ReadModel structs to determine which entities have read models
  • Report any entities present in code but missing from the matrix

5. Commit Convention Consistency

  • Read commit type definitions in docs/CONVENTIONS.md
  • Read commit references in CLAUDE.md and CONTRIBUTING.md
  • Verify all docs point to CONVENTIONS.md as canonical and don't define their own lists

6. Generated Code References

  • Verify internal/api/openapi.yaml exists
  • Verify internal/api/generated.go exists
  • Verify web/src/lib/api/types.generated.ts exists
  • Check that internal/api/generate.go has the correct go:generate directive

7. Dead Links

  • For each markdown file in the audit scope, check that internal document links (relative paths) point to files that actually exist

Output Format

Produce a structured report:

code
## Doc-Drift Audit Report

### Status: [PASS | DRIFT DETECTED]

### Architecture Tree (CLAUDE.md)
- [PASS/FAIL] Details...

### Package Organization (CONVENTIONS.md)
- [PASS/FAIL] Details...

### Technology List (CLAUDE.md)
- [PASS/FAIL] Details...

### Entity Status Matrix (INTEGRATION-MATRIX.md)
- [PASS/FAIL] Details...

### Convention Consistency
- [PASS/FAIL] Details...

### Generated Code
- [PASS/FAIL] Details...

### Link Integrity
- [PASS/FAIL] Details...

### Recommendations
- Numbered list of specific fixes needed (if any)

Be specific about what's wrong - quote the doc text and show the actual state. Only flag genuine mismatches, not trivial differences. If everything is in sync, say so - a clean audit is good news.