메뉴
Technical documentation standards — document structure, writing style, file organisation, mermaid diagrams, and validation. Referenced by do-docs and tech-docs-writer.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | do-tech-docs |
| description | Technical documentation standards — document structure, writing style, file organisation, mermaid diagrams, and validation. Referenced by do-docs and tech-docs-writer. |
| user-invocable | false |
| disable-model-invocation | true |
Produce technical documentation that explains what systems do, how they interact, and why specific choices were made.
Primary audience: LLMs. These docs will be loaded into LLM context windows during development tasks. Every token must earn its place. Write for machine comprehension first — dense, precise, and structurally consistent. Avoid prose padding, narrative flow, and filler sentences that a human might appreciate but an LLM gains nothing from.
Avoid documenting business processes or product capabilities.
A project is a mono-repo if any of the following are present:
package.json with a workspaces fieldpnpm-workspace.yamllerna.jsonCargo.toml with a [workspace] sectiongo.work filepyproject.toml files in subdirectoriesnx.jsonrush.jsonIf none of these indicators are found, treat the project as a single-repo.
This determination controls where documentation is stored — see File Organisation.
When documenting a full project (not a single component), include a brief onboarding section in architecture-overview.md or a dedicated getting-started.md:
Keep to under 20 lines. This is the one context where CLI commands are acceptable.
Every document must start with a YAML frontmatter block. This gives an LLM immediate context about what the document covers without reading the full body.
---
title: <descriptive title>
scope: <component | service | architecture | decision>
relates-to: [list of other doc filenames this connects to]
last-verified: <YYYY-MM-DD when last checked against source code>
---
## Overview
<1-2 sentences: what this covers, stated as facts not narrative.>
## <Core Content>
<Main documentation. Use H2/H3 headings as section labels. Prefer bullet points and tables over paragraphs. Each section should be independently useful — an LLM may retrieve a single section, not the whole document.>
## Integration Points
<How this component connects to others. Include a Mermaid diagram.>
## Design Decisions
<Decision: rationale format. No preamble.>
Docs are loaded into LLM context alongside code, conversation history, and tool results. Context is finite and expensive.
docs/
technical/ — root-level / cross-cutting technical docs
product/ — product documentation (features, user guides, business context)
maverick/ — maverick-generated project skills (if applicable)
All technical docs go in docs/technical/ — no additional nesting required.
docs/technical/ at the repo root<package>/docs/ (no technical/ subdirectory needed since package docs are inherently technical)<package>/docs/ maintains its own index.md listing that package's documentsdocs/product/kebab-case.md naming (e.g. authentication-architecture.md)relates-to in frontmatterindex.md in docs/technical/ listing all documents with one-line descriptions — this serves as the entry point for LLM context loadingdocs/technical/index.md should link to each <package>/docs/index.md| Task size | Documentation depth |
|---|---|
| Trivial (config, minor change) | 2-3 sentences in an existing doc or commit message |
| Small (single component) | Overview + core content (under 200 lines) |
| Medium (feature, service) | Full document structure (200-500 lines) |
| Large (cross-cutting, architecture) | Split into multiple focused documents |
Scale section depth to component complexity. Indicators that a component needs deeper coverage:
For these components, document each distinct responsibility separately rather than summarising the whole.
Use diagrams to visualise:
sequenceDiagram or flowchartflowchart or sequenceDiagramflowchart or C4ContextstateDiagram-v2Guidelines:
key: value patterns, bullet lists, and tables. Reserve prose for explaining why — rationale that cannot be expressed as a list.Before finalising documentation:
docs/technical/index.md updated if this is a new document (and <package>/docs/index.md for mono-repo package docs)Scan a project for missing best-practice areas and implement the top recommendation for each gap (linting, unit testing) — installs tools, writes configs, verifies, and commits. Pass 'recommend' to stop after writing recommendations without implementing (replaces the old do-recommend skill).
Implement a focused code change. Use this skill as the wrapper for any implementation work so the Maverick workflow report captures what was done and so the agent applies the project's coding standards before editing. Intended to be invoked once per task from inside a do-issue-* or do-epic phase, not standalone.
Audit a codebase for security risks in one of two modes. In full-audit mode it scans the entire codebase and writes a findings report to docs/security-audit.md (run as part of do-init or on demand). In update mode it reviews only a diff plus the code it could impact, returning a structured findings list as a pre-push gate for do-issue-solo and do-issue-guided. Covers secrets exposure, dependency vulnerabilities, authentication and authorisation patterns, input validation, transport security, and common OWASP risks.
Create, restructure, or update technical documentation. Handles greenfield projects, refactoring non-compliant docs, and incremental updates after code changes.
Work on a multi-story GitHub epic end-to-end. Builds a DAG from the child stories, groups them into waves, runs waves in parallel via per-story worktrees, ejects PRs that fail agent-code-review for human handling, and propagates blocks to downstream stories. Requires git worktrees.
Initialise a project for use with Maverick — verifies the GitHub App, installs the CLI if needed, writes the project config with integration tracking, scaffolds docs, generates project skills, runs an initial cybersecurity audit, then commits the changes and opens a PR.