Communityライティング&編集github.com

SmallNoc/noc-living-docs

Living docsプロトコルとCodexスキル。AI支援によるコード変更、要件、ステータス、ガードレール、テスト、変更記録を同期します。

noc-living-docs とは?

このスキルは、プロジェクトの「生きたドキュメント(living docs)」を実行可能なプロジェクトメモリとして活用するためのプロトコルとツールを提供します。AIエージェント(特にCodex)がコード変更を行う際に、要件、ステータス、ガードレール、テスト結果、変更履歴を常に同期し、一貫性を保ちます。具体的には、`noc_docs/` ディレクトリを管理し、Pythonスクリプト `noc.py` を使ってワークプランの生成、インデックス作成、変更前チェックを実行します。これにより、AIが自律的にコードを変更する際に、ドキュメントの陳腐化を防ぎ、プロジェクトの知見を常に最新の状態に保つことができます。主にCodexエージェントでの使用を想定していますが、プロトコル自体は汎用的です。

対応~Claude Code✓Codex CLI~Cursor
npx skills add SmallNoc/noc-living-docs

Installed? Explore more ライティング&編集 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

プロジェクト生きたドキュメント

NOC Living Docsを実行可能なプロジェクトメモリとして使用してください。noc_docs/ を経由し、影響を受けるドキュメントのみを読み、コードや意図が変更されたら生きたドキュメントを更新し、CLIで検証します。

トリガー

このスキルは以下の場合に使用します:

  • noc_docs/ の初期化または移行
  • 要件について議論した後のコード変更
  • 新機能、バグ修正、リファクタリング、API/データ/セキュリティ/デプロイメントの変更
  • コード変更がドキュメント更新を必要とするかどうかの確認
  • プロジェクトの生きたドキュメントのクエリまたは監査

プロジェクトメモリ、コード動作、要件、ガードレール、テスト、またはNOCドキュメントに関係のない一般的な質問には使用しないでください。

実行手順

  1. リクエスト、変更されたパス、および noc_docs/.living-docs/feature-map.json から影響を受ける機能/ドメインを特定します。
  2. コードが変更される可能性がある場合、ワークプランを実行します:
python scripts/noc.py work /path/to/project --feature <feature> --intent "<合意された要件>"

機能名よりもパスが明確な場合は、--path <code/path> を使用します。

  1. 最小限の関連ドキュメントを読みます:agent-guide.md、requirements.md、status.md、guardrails.md、test-record.md、およびドメイン固有のガードレール(存在する場合)。
  2. 確認された新しい/変更された意図を requirements.md に書き込みます。不確かな議論は notes.md に記録します。
  3. コードを変更します。
  4. 動作、検証、重要な変更、または制約が変更された場合、status.md、test-record.md、change-record.md、guardrails.md を更新します。
  5. ドキュメント、機能、またはマッピングが変更された後、python scripts/noc.py index <project> を実行します。
  6. Gitが利用可能な場合、コミット前に python scripts/noc.py check <project> --staged --warn-only を実行します。

詳細なワークフロールールについては、references/workflow.md を参照してください。

続行しない場合

以下の場合、コードを編集する前に停止してユーザーに確認します:

  • リクエストが guardrails.md またはドメインガードレールと矛盾する
  • 製品の意図が requirements.md と矛盾し、目的の方向性が不明確である
  • 影響を受ける機能/ドメインを特定できず、変更が明らかにグローバルではない
  • 必要なドキュメントが欠落しており、タスクが未知の要件や制約に依存している
  • ユーザーが現在のコードに合わせて要件を黙って書き換えるよう要求する
  • 変更がセキュリティ、権限、課金、データ損失、移行、または公開API契約に影響し、要求された動作が曖昧である

完了条件

このスキルを使用したタスクは、以下の場合にのみ完了とします:

  • 影響を受けるドキュメントが機能マップ、パス、または明示的な機能名を通じて特定された
  • 必要なドキュメントが読まれたか、欠落しているドキュメントが指摘された
  • コード変更とドキュメント変更が一致する
  • requirements.md は意図された動作変更に対してのみ変更された
  • status.md はコード変更後の現在の動作を反映している
  • test-record.md は検証を記録するか、検証が実行されなかった理由を説明している
  • change-record.md は重要な実装変更を記録している
  • インデックス/チェックが利用可能な場合は実行されたか、理由とともにスキップされた

最終応答形式

以下の形式で終了します:

NOC Living Docs:
- 確認したドキュメント:
- 更新したドキュメント:
- 意図的に変更しなかったドキュメント:
- 実行したコマンド:
- 実施したテスト:
- 残存リスク:

リストは簡潔に保ってください。該当しないカテゴリには なし を使用します。

参照

  • references/workflow.md: モード選択、フォールバックルール、競合処理、ワークループ
  • references/feature-doc-template.md: 各機能ドキュメントに含めるべき内容
  • references/domain-mode-guide.md: ドメインモードの使用時期と方法
  • references/codex-prompts.md: Codexの計画/目標/コードワークフロー向けの推奨ユーザープロンプト

関連スキル