NOC Living Docs

A local project-memory Skill for Codex, with a CLI that handles setup and one-time project initialization.

Start in three steps

1. Install

pipx install noc-living-docs
noc setup

2. Initialize a project once

cd my-project
noc init .

3. Use Codex normally

帮我给登录接口增加失败次数限制。

• You do not need to run work, index, check, feature, or suggest-map yourself.
• The Codex Skill automatically reads the smallest useful project memory.
• It updates memory only when a change creates a durable fact that future Codex sessions must know.
• Ordinary Bug fixes and small refactors do not create documentation work.
• NOC does not call a model or upload code; all project memory stays in your project.

中文说明在下方：中文。

License note: you can read and use this for learning, research, and personal non-commercial work. Commercial use needs written permission.

Advanced usage

The commands and protocol details below are optional. The Codex Skill runs the relevant commands automatically during normal development.

Why NOC

AI coding agents are fast, but project memory is fragile.

Common failure modes:

• Requirements stay in chat and disappear with the session.
• Current behavior is buried in code, old PRs, or someone's memory.
• Guardrails get forgotten when a new agent starts fresh.
• Test commands and gaps are not recorded.
• Agents read too much, miss the important file, or confidently infer the wrong thing.

NOC gives each feature a stable documentation home and gives agents one deterministic first step:

noc work . --path src/auth/login.py --json

That command answers: what feature is this, how confident is the mapping, which docs should I read, and what should I update after the code changes?

What It Looks Like

Given a path like scripts/noc.py, NOC can return a work plan like this:

{
  "schema_version": "1.0",
  "resolution_status": "resolved",
  "paths": ["scripts/noc.py"],
  "features": [
    {
      "id": "cli-core",
      "matched_by": "path",
      "matched_pattern": "scripts/noc.py",
      "confidence": "high",
      "read_before_code": [
        "noc_docs/features/cli-core/agent-guide.md",
        "noc_docs/features/cli-core/status.md",
        "noc_docs/features/cli-core/guardrails.md",
        "noc_docs/features/cli-core/test-record.md"
      ],
      "update_after_code": [
        {
          "doc": "noc_docs/features/cli-core/status.md",
          "reason": "when actual behavior changes"
        },
        {
          "doc": "noc_docs/features/cli-core/test-record.md",
          "reason": "with verification commands and results"
        }
      ]
    }
  ],
  "next_actions": []
}

If NOC cannot resolve a path, it says so explicitly with resolution_status: "unresolved" and suggests the next command, such as noc suggest-map or noc feature create.

Alternative installation

With pip:

python -m pip install noc-living-docs
noc setup

The package installs the noc CLI. noc setup, available since 1.1.0, installs the bundled, matching-version project-living-docs Skill into Codex. Run both once per machine.

For local development without installing:

git clone https://github.com/SmallNoc/noc-living-docs.git
cd noc-living-docs
python scripts/noc.py --help

Update

If installed with pipx:

pipx upgrade noc-living-docs

If installed with pip:

python -m pip install --upgrade noc-living-docs

If running from source:

git pull
python scripts/noc.py --help

After updating an existing NOC-enabled project, refresh indexes:

noc index /path/to/project
noc doctor /path/to/project

Advanced CLI workflow

Add NOC to a project:

noc init /path/to/project
noc doctor /path/to/project

Create docs for a real feature and map code to it:

noc feature create /path/to/project user-login --path src/auth/

Before changing code, route the agent:

noc work /path/to/project --path src/auth/login.py --json

Or route from Git state:

noc work /path/to/project --staged --json
noc work /path/to/project --changed --json

After changing code, update only the facts that changed, then verify:

noc index /path/to/project
noc check /path/to/project --staged

Advanced daily use

Use this loop for normal feature work:

1. Run noc work <project> --path <code/path> --json.
2. Read only the docs listed in read_before_code.
3. Change code.
4. Update only the docs whose facts changed.
5. Run noc index <project>.
6. Run noc check <project> --staged.

Use this loop when changes are already in Git:

noc work . --changed --json
noc work . --staged --json

Use this loop when NOC cannot resolve a path:

noc suggest-map . --interactive
noc feature create . <feature> --path <code/path>
noc index .

Advanced agent workflow

Before code:

1. Run noc work <project> --path <code/path> --json, or use --staged / --changed.
2. Read only the docs listed in the work plan.
3. Stop and ask if a requested change conflicts with guardrails.md.
4. Put confirmed new intent in requirements.md; put uncertainty in notes.md.

After code:

1. Update status.md when actual behavior changed.
2. Update test-record.md with commands, results, and gaps.
3. Update change-record.md for important changes worth remembering.
4. Update requirements.md only when intended behavior changed.
5. Run noc index and noc check --staged.

The point is not to update every file every time. The point is to keep the few facts future agents will need.

Advanced command reference

Use noc <command> --help for arguments.

Generated Documents

Default small mode creates:

<project>/
  AGENTS.md
  noc_docs/
    docs-map.md
    project-status.md
    development/
      documentation-policy.md
      git-workflow.md
      testing.md
    features/
      index.md
      _feature/
        agent-guide.md
        requirements.md
        status.md
        guardrails.md
        test-record.md
        change-record.md
        notes.md
    .living-docs/
      config.json
      docs-index.json
      feature-map.json
      manifest.json

AGENTS.md can be replaced by CLAUDE.md or GEMINI.md:

noc init /path/to/project --agent-file CLAUDE.md
noc init /path/to/project --agent-file GEMINI.md

_feature/ is a template placeholder. Real feature docs are created with:

noc feature create /path/to/project user-login --path src/auth/

That creates:

noc_docs/features/user-login/
  agent-guide.md
  requirements.md
  status.md
  guardrails.md
  test-record.md
  change-record.md
  notes.md

Document Responsibilities

Machine Files

The .living-docs/ directory is generated and maintained by noc index.

Agents should read feature-map.json through noc work --json rather than parsing it by hand.

Domain Mode

Bigger projects can use domain mode:

noc init /path/to/project --mode domain

Domain mode creates:

noc_docs/
  domains/
    index.md
    _domain/
      index.md
      guardrails.md
      features/
        _feature/
          agent-guide.md
          requirements.md
          status.md
          guardrails.md
          test-record.md
          change-record.md
          notes.md

Use domain mode for monorepos, multi-service systems, or teams with domain-level guardrails.

How It Compares

NOC can coexist with all of these. It is the local routing layer that tells an agent where to look before it edits code.

For Coding Agents

noc setup installs the bundled project-living-docs Skill into Codex's global Skill directory and keeps its version aligned with the CLI:

noc setup

The repository paths .agents/skills/project-living-docs and skills/codex/project-living-docs remain available for source development and compatibility.

Generic agents can read the managed block from:

noc init /path/to/project --agent-file AGENTS.md

See Agent Compatibility for details.

Developing This Repo

python scripts/noc.py validate
python scripts/release.py --check
python -m unittest tests.test_noc_cli tests.test_release_cli

python -m py_compile scripts/noc.py scripts/init-noc-docs.py scripts/index-noc-docs.py scripts/release.py scripts/validate-noc-docs.py

Current version: 1.2.0.

GitHub Discovery

Suggested GitHub topics:

codex
codex-skill
agent-skills
ai-coding
agents-md
living-docs
developer-tools
documentation
cli
git-hooks
project-memory

More reading:

• Why NOC
• Agent Compatibility
• Comparisons
• Release
• v1 Readiness
• Migration Reports

License

This repo is source-available and non-commercial by default.

Code, scripts, templates, and skills are licensed under the PolyForm Noncommercial License 1.0.0. For commercial use, get written permission first.

中文

NOC 是 Codex 的本地项目记忆 Skill，CLI 负责安装和一次性项目初始化。

三步开始使用

1. 安装：

   pipx install noc-living-docs
   noc setup
   

2. 每个项目初始化一次：

   cd my-project
   noc init .
   

3. 此后正常向 Codex 提出开发需求。无需手动运行 work、index、check、feature 或 suggest-map。

Codex Skill 会自动读取最小项目记忆，并且只在产生未来会话必须知道的新事实时更新记录。普通 Bug 修复和小型重构不会带来文档负担。NOC 不调用模型、不上传代码，所有记录都保存在项目本地。

高级用法

以下命令和协议细节均为可选内容；正常开发时由 Codex Skill 自动调用相关命令。

NOC 是给代码仓库用的轻量级 agent memory router。

它帮助 AI 编程助手在改代码前找到最小但有用的项目上下文，并在改完后留下未来会话需要的事实：当前行为、需求、限制、测试和重要变更。

NOC 保持本地、小而硬。它不调用模型、不运行服务端、不替代 issue tracker，也不试图变成 Wiki。

为什么需要 NOC

AI agent 写代码很快，但项目记忆很容易丢：

• 需求留在聊天里，换会话就消失。
• 当前行为藏在代码、旧 PR 或某个人的记忆里。
• guardrails 被新会话忘掉。
• 测试命令和测试缺口没有沉淀。
• agent 读太多、读错文件，或者自信地猜错。

NOC 给每个功能一个稳定的文档位置，也给 agent 一个确定的第一步：

noc work . --path src/auth/login.py --json

这个命令会回答：这是什么 feature、映射置信度如何、应该先读哪些文档、改完后可能要更新什么。

效果示例

给定 scripts/noc.py 这样的路径，NOC 可以返回这样的 work plan：

{
  "schema_version": "1.0",
  "resolution_status": "resolved",
  "paths": ["scripts/noc.py"],
  "features": [
    {
      "id": "cli-core",
      "matched_by": "path",
      "matched_pattern": "scripts/noc.py",
      "confidence": "high",
      "read_before_code": [
        "noc_docs/features/cli-core/agent-guide.md",
        "noc_docs/features/cli-core/status.md",
        "noc_docs/features/cli-core/guardrails.md",
        "noc_docs/features/cli-core/test-record.md"
      ],
      "update_after_code": [
        {
          "doc": "noc_docs/features/cli-core/status.md",
          "reason": "when actual behavior changes"
        },
        {
          "doc": "noc_docs/features/cli-core/test-record.md",
          "reason": "with verification commands and results"
        }
      ]
    }
  ],
  "next_actions": []
}

如果 NOC 无法解析路径，它会明确返回 resolution_status: "unresolved"，并建议下一步命令，例如 noc suggest-map 或 noc feature create。

其他安装方式

也可以使用 pip：

python -m pip install noc-living-docs
noc setup

安装包提供 noc CLI；从 1.1.0 开始，noc setup 会把同版本的 project-living-docs Skill 安装到 Codex。每台机器只需执行一次。

本地开发不安装时：

git clone https://github.com/SmallNoc/noc-living-docs.git
cd noc-living-docs
python scripts/noc.py --help

更新

如果使用 pipx 安装：

pipx upgrade noc-living-docs

如果使用 pip 安装：

python -m pip install --upgrade noc-living-docs

如果使用源码：

git pull
python scripts/noc.py --help

已有项目升级后，刷新索引：

noc index /path/to/project
noc doctor /path/to/project

高级 CLI 工作流

给项目接入 NOC：

noc init /path/to/project
noc doctor /path/to/project

创建真实 feature 并映射代码路径：

noc feature create /path/to/project user-login --path src/auth/

改代码前，先路由 agent：

noc work /path/to/project --path src/auth/login.py --json

或者从 Git 状态路由：

noc work /path/to/project --staged --json
noc work /path/to/project --changed --json

改完代码后，只更新真的变化了的事实，然后验证：

noc index /path/to/project
noc check /path/to/project --staged

高级日常使用

普通功能开发使用这个循环：

1. 运行 noc work <project> --path <code/path> --json。
2. 只读 read_before_code 列出的文档。
3. 修改代码。
4. 只更新事实发生变化的文档。
5. 运行 noc index <project>。
6. 运行 noc check <project> --staged。

如果代码已经改了，可以从 Git 状态生成 work plan：

noc work . --changed --json
noc work . --staged --json

如果 NOC 无法解析路径：

noc suggest-map . --interactive
noc feature create . <feature> --path <code/path>
noc index .

高级 Agent 工作流

改代码前：

1. 运行 noc work <project> --path <code/path> --json，或者用 --staged / --changed。
2. 只读 work plan 里列出的文档。
3. 如果请求和 guardrails.md 冲突，停下来问用户。
4. 已确认的新意图写进 requirements.md；不确定的问题写进 notes.md。

改代码后：

1. 当前行为变了，更新 status.md。
2. 写入测试命令、结果和缺口到 test-record.md。
3. 重要变更写进 change-record.md。
4. 只有目标行为变了，才更新 requirements.md。
5. 运行 noc index 和 noc check --staged。

重点不是每次更新所有文件，而是保留未来 agent 真正需要的少数事实。

高级命令参考

参数细节可运行 noc <command> --help。

生成的文档

默认 small 模式会生成：

<project>/
  AGENTS.md
  noc_docs/
    docs-map.md
    project-status.md
    development/
      documentation-policy.md
      git-workflow.md
      testing.md
    features/
      index.md
      _feature/
        agent-guide.md
        requirements.md
        status.md
        guardrails.md
        test-record.md
        change-record.md
        notes.md
    .living-docs/
      config.json
      docs-index.json
      feature-map.json
      manifest.json

AGENTS.md 可以替换成 CLAUDE.md 或 GEMINI.md：

noc init /path/to/project --agent-file CLAUDE.md
noc init /path/to/project --agent-file GEMINI.md

_feature/ 是模板占位目录。真实 feature 文档用下面的命令创建：

noc feature create /path/to/project user-login --path src/auth/

会生成：

noc_docs/features/user-login/
  agent-guide.md
  requirements.md
  status.md
  guardrails.md
  test-record.md
  change-record.md
  notes.md

文档职责

机器文件

.living-docs/ 目录由 noc index 生成和维护。

agent 应该通过 noc work --json 使用 feature-map.json，而不是手写解析它。

Domain 模式

大项目可以使用 domain 模式：

noc init /path/to/project --mode domain

domain 模式生成：

noc_docs/
  domains/
    index.md
    _domain/
      index.md
      guardrails.md
      features/
        _feature/
          agent-guide.md
          requirements.md
          status.md
          guardrails.md
          test-record.md
          change-record.md
          notes.md

monorepo、多服务系统，或者有领域级 guardrails 的团队适合使用 domain 模式。

和其他工具的关系

NOC 可以和这些工具共存。它是本地路由层，告诉 agent 改代码前应该看哪里。

给 Coding Agents 使用

noc setup 会把内置的 project-living-docs Skill 安装到 Codex 的全局 Skill 目录，并保持 Skill 与 CLI 版本一致：

noc setup

仓库中的 .agents/skills/project-living-docs 和 skills/codex/project-living-docs 继续用于源码开发和兼容旧用法。

通用 agent 可以读取 managed block：

noc init /path/to/project --agent-file AGENTS.md

细节见 Agent Compatibility。

开发本仓库

python scripts/noc.py validate
python scripts/release.py --check
python -m unittest tests.test_noc_cli tests.test_release_cli

python -m py_compile scripts/noc.py scripts/init-noc-docs.py scripts/index-noc-docs.py scripts/release.py scripts/validate-noc-docs.py

当前版本：1.2.0。

GitHub 发现性

建议添加这些 GitHub topics：

codex
codex-skill
agent-skills
ai-coding
agents-md
living-docs
developer-tools
documentation
cli
git-hooks
project-memory

更多阅读：

• Why NOC
• Agent Compatibility
• Comparisons
• Release
• v1 Readiness
• Migration Reports

许可证

本仓库源码公开，默认用于非商业场景。

代码、脚本、模板和 skills 使用 PolyForm Noncommercial License 1.0.0。商业使用需要书面许可。