菜单
Use when documenting MeteorBurn/dj-track-similarity or when writing grounded technical and user-facing docs from an actual codebase; includes project-specific rules for the dj-track-similarity VitePress docs tree.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | codebase-documentation-writer |
| description | Use when documenting MeteorBurn/dj-track-similarity or when writing grounded technical and user-facing docs from an actual codebase; includes project-specific rules for the dj-track-similarity VitePress docs tree. |
Use this skill to document a repository from zero context without inventing behavior. For MeteorBurn/dj-track-similarity, this skill is project-aware: it should update the existing README.md plus the VitePress source tree under docs/dj-track-similarity/, preserve the project's local-first DJ-library safety model, and keep claims practical and modest.
The output should serve two audiences:
The job is not to make the project sound impressive. The job is to make the project understandable, accurate, and maintainable.
Unknown from current codebase or TODO: verify, not a confident guess.Treat the repository as dj-track-similarity when any of these are true:
https://github.com/MeteorBurn/dj-track-similarity;pyproject.toml has name = "dj-track-similarity";AGENTS.md describes a local DJ music-library analysis workbench;src/dj_track_similarity/ and docs/dj-track-similarity/.When detected, follow the project-specific section below before the generic workflow.
For this project, docs are navigation aids, not the authority for logic. Verify behavior from current source, tests, schemas, and runtime evidence.
Read these first:
AGENTS.mdREADME.mdpyproject.tomldocs/dj-track-similarity/project-guide.mddocs/dj-track-similarity/.vitepress/config.mtsdocs/dj-track-similarity/developer/architecture.mddocs/dj-track-similarity/developer/development.mddocs/dj-track-similarity/developer/testing-and-verification.mdsrc/dj_track_similarity/cli.pysrc/dj_track_similarity/api.pysrc/dj_track_similarity/api_schemas.pyfrontend/src/api.tsDo not rely on stale docs when source or tests disagree. If you find a mismatch, document the current source behavior and note the docs inconsistency for review.
Keep public claims practical and modest:
Avoid marketing filler such as enterprise-grade, seamless, state-of-the-art, robust AI, or production-ready unless the source and tests prove exactly that. They usually do not.
Use the current checkout as source of truth. The current main branch uses this tracked documentation surface:
README.md
docs/dj-track-similarity/
The current main English entrypoint is:
docs/dj-track-similarity/project-guide.md
On current main, do not create a generic root docs layout like:
docs/architecture.md
docs/user-guide.md
docs/api.md
That would be wrong for current main. Use the existing VitePress sections instead:
docs/dj-track-similarity/getting-started/
docs/dj-track-similarity/user-guide/
docs/dj-track-similarity/workflows/
docs/dj-track-similarity/concepts/
docs/dj-track-similarity/tools-and-scripts/
docs/dj-track-similarity/reference/
docs/dj-track-similarity/developer/
docs/dj-track-similarity/help/
Branch-sensitive rule: older or alternate branches such as dev / maim-backup may have a flatter docs layout, Russian docs/dj-track-similarity/ru/ pages, generated docs/dj-track-similarity/site/, or different route/tool surfaces. When working on any non-main checkout, re-read that checkout's AGENTS.md, README.md, docs tree, and .vitepress/config.mts before editing. Preserve the branch-local docs structure instead of forcing the current-main structure onto it.
If adding a new VitePress page, also update:
docs/dj-track-similarity/.vitepress/config.mts
and the nearest section index.md when that branch uses section index pages. Otherwise the page exists but users will not find it. Tiny orphan docs are how documentation becomes a haunted attic.
docs/dj-track-similarity/, prefer python ... or the installed dj-sim console script..\.venv\Scripts\python.exe unless documenting a local troubleshooting command where that exact path matters.High-level map:
src/dj_track_similarity/: backend, Typer CLI, FastAPI routes, SQLite access, scanning, analysis, embeddings, classifiers, search, exports, tags, media preview, logging, runtime helpers.frontend/: React/Vite/TypeScript UI. frontend/src/api.ts mirrors backend API contracts; frontend/dist is the backend-served bundle.tests/: backend/API/search/jobs/tags/evaluation pytest coverage.scripts/: focused maintenance and benchmark scripts plus script tests.docs/dj-track-similarity/: VitePress source; npm run build writes ignored site/ output.tools/rhythm-lab/: standalone classifier labeling/training UI and CLI.tools/audio-doctor/: dry-run-first metadata/container diagnostic and repair helper plus UI jobs.tools/audio-dedup/: duplicate-audio candidate reporter plus explicit confirmed cleanup mode.Hot source areas:
database.py, db_schema.py, db_*, LibraryDatabase.api.py, api_schemas.py, api_routes_*.py, frontend/src/api.ts.cli.py with dj-sim, eval, classifier, and index command groups.scanner.py, audio_loader.py, media_preview.py.analysis_jobs.py, analysis_config.py, analysis_model_runners.py, sonara_features.py, genres.py, embedding.py.search.py, sonara_similarity.py, sonara_similarity_scoring.py, hybrid_search.py, set_builder.py, transition_diagnostics.py.tags.py, wave_tags.py, exporter.py.classifier_manifest.py, classifier_production.py, classifier_scoring.py, classifier_jobs.py, rhythm_lab_collections.py, rhythm_lab_launcher.py.tools/audio-doctor/, tools/audio-dedup/, tools/rhythm-lab/.Do not weaken or blur these invariants:
.aif/.aiff to temporary WAV for streaming, but it must not rewrite or cache source audio./api/tags/genres/apply is the explicit standard genre tag write path. It writes only the stored MAEST-derived genre field and preserves normal tags such as title, artist, album, BPM, and key.TCON; do not document custom RIFF repair as part of the app tag-write path.LibraryDatabase with path-scoped write locking, WAL, and busy timeout.dj-track-similarity.sqlite and user-selected .sqlite files are local user state.tracks.path values only; it does not move, copy, delete, or retag audio.--apply may rewrite only files previously reported as REPAIRABLE, runs sequentially, and creates backups by default.APPLY REPAIR confirmation.--apply requires exact APPLY DELETE, deletes only safe duplicate candidates inside selected --root, and removes SQLite rows only for tracks whose files were deleted.track_classifier_scores.classifier_key; do not imply one classifier recomputes or deletes another classifier's scores.tools/rhythm-lab/data/.ffmpeg on PATH or DJ_TRACK_SIMILARITY_FFMPEG.8765, Vite frontend 5173, Rhythm Lab 8777.When adding or updating docs, choose the right page family:
getting-started/quickstart.md, install.md, first-library.md, first-analysis.md.user-guide/browse-library.md, analyze-library.md, search-with-seeds.md, smart-set-builder.md, text-search.md, class-tab.md, export-playlists.md, tags-and-audio-writes.md.workflows/prepare-a-set.md, find-compatible-tracks.md, build-crates.md, train-personal-classifier.md, maintain-library.md.concepts/local-first-safety.md, features-embeddings-tags.md, similarity-scores.md, smart-set-builder-routing.md, classifiers-and-rhythm-lab.md.tools-and-scripts/rhythm-lab.md, audio-dedup.md, audio-doctor.md, persistent-ann-indexes.md, optimize-database.md.reference/cli.md, api.md, database.md, configuration.md, analysis-families.md, ui-controls.md.developer/architecture.md, development.md, testing-and-verification.md, release-checklist.md.help/troubleshooting.md, faq.md, known-limits.md.If changing README, keep it short and link to these pages instead of duplicating whole references.
Before changing docs:
git status --short --branch
git diff --stat
Current main uses Vale for public documentation style. Read .vale.ini, .vale/styles/config/vocabularies/DJTrackSimilarity/accept.txt, and docs/dj-track-similarity/scripts/run-vale.mjs before changing lint behavior or vocabulary.
After Markdown-only docs changes, run at least:
git diff --check -- README.md docs/dj-track-similarity
cd docs\dj-track-similarity
npm run check
npm run check runs strict Vale style checking for README.md plus the VitePress Markdown tree, then builds the static docs. On a fresh checkout or after .vale.ini package changes, run once first:
cd docs\dj-track-similarity
npm run vale:sync
Use this while editing when you want style findings without failing the command:
cd docs\dj-track-similarity
npm run lint:style
Do not commit generated docs/dj-track-similarity/site/ output unless the branch explicitly tracks it.
If the change affects source behavior, use the project verification matrix from AGENTS.md. Common checks:
python -m pytest
cd frontend
npm run build
cd ..\docs\dj-track-similarity
npm run check
Use focused tests for touched behavior rather than full slow runs when appropriate. Examples:
python -m pytest tests\test_api_text_search.py --override-ini addopts=
python -m pytest tests\test_api_set_builder.py --override-ini addopts=
python -m pytest tests\test_tags.py --override-ini addopts=
python -m pytest tools\rhythm-lab\tests\test_rhythm_lab.py --override-ini addopts=
Do not run destructive helper apply modes just to verify docs.
Use this section for other repositories, or as the base process before applying the dj-track-similarity profile.
First read repository guidance and docs:
AGENTS.md, CLAUDE.md, .cursorrules, .cursor/rules/*, .agents/*, .codex/*README*, CONTRIBUTING*, ARCHITECTURE*, TESTING*, CHANGELOG*docs/, examples/, scripts/, CI files, Docker files, package manifestsCheck repository state before edits:
git status --short --branch || true
git diff --stat || true
If the tree is dirty, avoid broad rewrites and mention pre-existing changes in the final report.
Map the project:
Write a short internal plan before editing docs:
## Repository map
## Existing docs
## Runtime and dev commands
## Architecture findings
## User-facing behavior
## Proposed docs
## Risks and unknowns
Prefer existing project conventions. If none exist, use this default shape where applicable:
README.md # overview, quickstart, docs index
docs/
architecture.md # architecture and module map
developer-guide.md # local dev, tests, contribution workflow
user-guide.md # user-facing setup and usage
configuration.md # env vars, config files, feature flags
operations.md # deploy/run/backup/monitor/troubleshoot, if applicable
api.md # APIs, CLI commands, events, contracts, if applicable
troubleshooting.md # known failures and fixes
For dj-track-similarity, do not use this generic layout. Use the VitePress tree described above.
Adapt by project type:
Technical docs should include:
Use concrete references, for example:
server.py defines the HTTP app and health route.src/auth/session.ts manages session cookies.package.json exposes npm run test and npm run build.Do not write vague filler like robust scalable architecture unless the repo proves it.
User docs should answer:
Keep user docs task-oriented. Avoid dumping internal architecture into the user guide unless it helps the user make a decision or fix a problem.
After writing, verify rather than trusting your own final message.
Minimum verification:
git diff --stat
git diff -- README.md docs/ || true
If project tooling exists, run the relevant safe docs/build checks:
npm run docs:build || npm run build || true
pnpm docs:build || pnpm build || true
make docs || true
mkdocs build || true
sphinx-build -b html docs docs/_build/html || true
Do not run destructive commands, deployments, migrations, publishes, credential setup, deletes, resets, or external side-effect workflows just to verify documentation.
Check local markdown links when no docs tool exists:
python3 - <<'PY'
from pathlib import Path
import re
roots = [Path('README.md'), Path('docs')]
files = []
for root in roots:
if root.is_file():
files.append(root)
elif root.is_dir():
files.extend(root.rglob('*.md'))
for p in files:
text = p.read_text(encoding='utf-8', errors='replace')
for m in re.finditer(r'\[[^\]]+\]\(([^)]+)\)', text):
target = m.group(1).split('#', 1)[0]
if not target or '://' in target or target.startswith('mailto:'):
continue
q = (p.parent / target).resolve()
if not q.exists():
print(f'BROKEN_LINK {p}:{m.start()} -> {target}')
PY
When done, report:
Documentation updated.
Changed files:
- `path` - what changed
Verification:
- `command` - result
Grounding examples:
- `doc claim` is based on `source path/symbol`
Still unknown / needs human input:
- `item`, or `None`
dj-track-similarity, do not create docs outside the current checkout's tracked README/docs surface unless the user explicitly asks.