Imported from young1lin/cc-tutorial (
AGENTS.md). Install upstream withnpx skills add young1lin/cc-tutorial. Copyright stays with the author.
Repository Guidelines
Project Structure & Module Organization
This repository is a Claude Code tutorial, not a single application. Keep changes scoped to the content area you are editing:
video-scripts/: the main 9-layer course scripts, named with zero-padded prefixes such aslayer-01-theory.md.docs/: published articles and images.research/: source-backed research notes. Add new entries asNN-descriptive-name.mdand updateresearch/00-research-summary.md.examples/http/: runnable.httpAPI examples for REST Client or JetBrains HTTP Client.examples/python/andexamples/asr/: Python example projects managed withuv..claude/commands/: project-specific Claude Code workflows such as/commit-push.
Build, Test, and Development Commands
There is no repo-wide build. Use the command that matches the area you changed:
cd examples/python && uv sync: install the Python example dependencies.cd examples/python && uv run python 00_basic_function_calling.py 1: run a sample Python demo.cd examples/asr && uv sync: install the ASR example dependencies.cd examples/asr && uv run python main.py: start the ASR demo locally.- Open
examples/http/*.httpin VS Code REST Client or a JetBrains IDE and send requests interactively.
Coding Style & Naming Conventions
Use concise Markdown, short sections, and concrete examples. For Python, follow PEP 8 with 4-space indentation. Match existing naming patterns:
- ordered tutorial files:
layer-02-setup.md,01-main.http - documentation and research files: kebab-case
- helper scripts: descriptive snake_case or existing local convention
When adding tutorial analysis or opinionated guidance, clearly label it as author interpretation rather than fact.
Project Writing Rules
Evidence Rules
If it is a fact, prove it. If it cannot be proved, do not present it as fact.
- Use these evidence tiers:
T1: official vendor or platform documentation, changelogs, or engineering postsT2: recognized expert practitioner material such as books, talks, blogs, or coursesT3: community consensus supported by at least two independent sourcesT4: author interpretation, tutorial framing, opinion, or prediction
- Any statement about feature existence, product behavior, pricing, limits, benchmarks, statistics, chronology, or technical capability must be traceable to a source.
- Prefer
T1for feature existence, official behavior, and product capability claims. - Use
T1orT2for performance claims and any superlative or absolute wording such asbest,fastest,only,always, ornever. - If strong proof does not exist, downgrade the claim to
T4, mark it explicitly, and narrow the wording. - Mark subjective guidance, predictions, teaching choices, and personal conclusions with one of:
**[Tutorial perspective]****[Author's analysis]**
- Treat all predictive claims as
T4and include the reasoning behind the prediction. - For
T3claims, cite at least two independent sources. - When experts disagree, surface the disagreement with citations before stating the tutorial's preferred view.
Research Workflow
When adding or expanding source-backed material:
- Search existing files in
research/first before creating a new note. - If a new source is needed, create
research/NN-descriptive-name.md. - New research files must include YAML front matter with:
titleauthordateurltiertopics
- Update
research/00-research-summary.mdwhenever a new research note is added. - Distinguish clearly between cited facts and tutorial interpretation.
Voice And Tone
Write like a ruthless analyst, not an assistant trying to sound helpful.
- Cut without mercy. If a sentence exists only to transition, soften, summarize, or sound "natural", delete it.
- Ban stock AI filler and stage-setting phrases such as
imagine,needless to say,all in all,it is undeniable,it is worth noting,in terms of,from this we can see, or any similar verbal padding. - Do not warm up. Do not ease in. Open with the point, the breakage, the mechanism, or the verdict.
- Favor short sentences. Hard stops. Clean cuts. Use long sentences only when they carry real technical weight.
- Prefer blunt judgments over polite vagueness. If something is weak, say it is weak. If it fails, say where it fails.
- Use sharp, concrete words. Avoid bloodless abstractions and consultant language.
- Use metaphors as weapons, not decorations. They must tighten the logic, raise the image, and land the consequence. Never explain them after the fact.
- Use rhetorical questions to puncture bad assumptions. Do not linger on the question. Answer it with the underlying logic.
- Do not hand out emotional reassurance. No cheerleading. No fake empathy. No empty balance.
- Do not perform neutrality. If one path is better, say so. Then justify it.
- Keep the tone cold, controlled, unsentimental, and precise.
- Final pass rule: if the piece still sounds like a polished model response, rewrite it until the edges show.
- When the content is factual, keep it evidence-backed. When it is interpretation, prediction, or judgment, mark it as
T4.
Testing Guidelines
No root test suite exists today. Verify contributions in the smallest relevant way:
- for Python examples, run the touched script with
uv run - for
.httpexamples, replay the edited request(s) - for Markdown changes, check links, headings, and code fences manually
If you add automated tests for new Python behavior, prefer pytest with test_*.py naming and keep tests close to the example they cover.
Commit & Pull Request Guidelines
Follow the conventional commit style already used in history, for example feat(examples): add real-time ASR subtitle example or docs(setup): simplify permissions config example.
When generating commit message trailers for AI-assisted commits:
- In
Claude Code, useCo-Authored-By: <Model Name> <noreply@anthropic.com>. - In
Codexor other OpenAI terminals, useCo-Authored-By: <Model Name> (Codex). - Do not use an Anthropic email outside Claude Code.
- Do not invent an OpenAI email unless the repository explicitly defines one.
PRs should include a short summary, the folders affected, verification commands or manual checks performed, and screenshots when updating image-backed docs or UI-like outputs.
Security & Configuration Tips
Do not commit secrets, local API keys, or .env files. Keep machine-specific settings in ignored local files, and avoid checking in generated binaries, logs, or temporary artifacts.
