AGENTS.md 实战：把仓库指令写成可维护的工程约定

import unittest

from packages.catalog.total import basket_total


class CatalogTests(unittest.TestCase):
    def test_total(self):
        self.assertEqual(basket_total([
            {"price_cents": 1099, "quantity": 2},
            {"price_cents": 399, "quantity": 1},
        ]), 2597)

    def test_empty(self):
        self.assertEqual(basket_total([]), 0)

    def test_free_item(self):
        self.assertEqual(basket_total([{"price_cents": 0, "quantity": 1}]), 0)

    def test_invalid_price(self):
        for price in (-1, 1.2, True, "10", None):
            with self.subTest(price=price), self.assertRaises(ValueError):
                basket_total([{"price_cents": price, "quantity": 1}])

    def test_invalid_quantity(self):
        for quantity in (0, -1, 1.2, True, None):
            with self.subTest(quantity=quantity), self.assertRaises(ValueError):
                basket_total([{"price_cents": 10, "quantity": quantity}])

    def test_invalid_shape(self):
        for rows in ({}, "text", [1], [{}]):
            with self.subTest(rows=rows), self.assertRaises(ValueError):
                basket_total(rows)

"""Small deterministic style check; not a complete Python formatter."""
import ast
from pathlib import Path


def check(root):
    errors = []
    for folder in ("packages", "tests", "tools"):
        for path in sorted((root / folder).rglob("*.py")):
            text = path.read_text(encoding="utf-8")
            rel = path.relative_to(root)
            try:
                ast.parse(text, filename=str(rel))
            except SyntaxError as exc:
                errors.append(f"{rel}: syntax error at {exc.lineno}")
            for number, line in enumerate(text.splitlines(), 1):
                if len(line) > 88 or line.rstrip() != line or "\t" in line:
                    errors.append(f"{rel}:{number}: style violation")
            if text and not text.endswith("\n"):
                errors.append(f"{rel}: missing final newline")
    return errors


if __name__ == "__main__":
    problems = check(Path(__file__).resolve().parents[1])
    print("\n".join(problems) if problems else "style: ok")
    raise SystemExit(bool(problems))

"""Validate this example's guidance manifest without running its commands."""
import argparse
from datetime import date
import hashlib
import json
from pathlib import Path
import re
import shlex
import shutil


def local_path(root, name):
    path = (root / name).resolve()
    if Path(name).is_absolute() or not path.is_relative_to(root.resolve()):
        raise ValueError(f"outside repository: {name}")
    return path


def command_errors(root, cwd, command):
    if any(char in command for char in ";|&><`$\n"):
        return ["shell operators are not allowed"]
    try:
        parts = shlex.split(command)
    except ValueError:
        return ["invalid quoting"]
    if len(parts) < 2 or parts[0] != "python3":
        return ["only python3 commands are supported"]
    if not shutil.which("python3"):
        return ["python3 executable is missing"]
    try:
        if parts[1:4] == ["-m", "unittest", "discover"]:
            tail = parts[4:]
            if tail not in (["-s", "tests", "-v"],
                            ["-s", "tests", "-p", "test_catalog.py", "-v"]):
                return ["unsupported unittest options"]
            tests = local_path(root, str(cwd / tail[1]))
            pattern = tail[3] if "-p" in tail else "test*.py"
            if not tests.is_dir() or not list(tests.glob(pattern)):
                return ["test directory or matching tests are missing"]
        elif parts[1] == "-m":
            if len(parts) != 4 or not re.fullmatch(r"[\w.]+", parts[2]):
                return ["unsupported module command"]
            module = parts[2].replace(".", "/") + ".py"
            if not local_path(root, str(cwd / module)).is_file():
                return [f"module is missing: {module}"]
            if not local_path(root, str(cwd / parts[3])).is_file():
                return [f"input is missing: {parts[3]}"]
        else:
            if len(parts) != 2 or not parts[1].endswith(".py"):
                return ["unsupported script command"]
            if not local_path(root, str(cwd / parts[1])).is_file():
                return [f"script is missing: {parts[1]}"]
    except ValueError as exc:
        return [str(exc)]
    return []


def lint(root, today):
    root = root.resolve()
    errors = []
    try:
        manifest_path = local_path(root, "tools/guide_manifest.json")
        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
        guides = manifest["guides"]
        max_age = manifest["max_age_days"]
        if not isinstance(guides, list) or type(max_age) is not int or max_age < 0:
            return ["invalid manifest shape"]
        for item in guides:
            name = item["path"]
            guide = local_path(root, name)
            if not guide.is_file():
                errors.append(f"{name}: guide is missing")
                continue
            content = guide.read_text(encoding="utf-8")
            digest = hashlib.sha256(guide.read_bytes()).hexdigest()
            if digest != item["sha256"]:
                errors.append(f"{name}: content changed; review manifest")
            age = (today - date.fromisoformat(item["reviewed"])).days
            if age < 0 or age > max_age:
                errors.append(f"{name}: review date is stale or in the future")
            cwd = Path(item["cwd"])
            if not local_path(root, str(cwd)).is_dir():
                errors.append(f"{name}: command directory is missing")
            for ref in item["refs"]:
                if not local_path(root, ref).exists():
                    errors.append(f"{name}: reference is missing: {ref}")
            blocks = re.findall(r"```sh\n(.*?)\n```", content, re.S)
            commands = [line for block in blocks for line in block.splitlines()]
            if not commands:
                errors.append(f"{name}: no checked command block")
            for command in commands:
                if not command.strip():
                    continue
                for error in command_errors(root, cwd, command):
                    errors.append(f"{name}: {error}: {command}")
    except (OSError, ValueError, KeyError, TypeError) as exc:
        errors.append(f"manifest error: {exc}")
    return errors


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--root", type=Path, default=Path(__file__).parents[1])
    parser.add_argument("--today", type=date.fromisoformat, default=date.today())
    args = parser.parse_args()
    errors = lint(args.root, args.today)
    print("\n".join(errors) if errors else "guidance: ok")
    return bool(errors)


if __name__ == "__main__":
    raise SystemExit(main())

{
  "max_age_days": 90,
  "guides": [
    {
      "path": "AGENTS.md",
      "reviewed": "2026-10-05",
      "cwd": ".",
      "refs": [
        "packages/catalog/AGENTS.md",
        "fixtures/order.json",
        "docs/ownership.md"
      ],
      "sha256": "938d8633614e22247a6f1d7f40ad38a8f892e0eb58c39a30481d1e70be2c0b8f"
    },
    {
      "path": "packages/catalog/AGENTS.md",
      "reviewed": "2026-10-05",
      "cwd": ".",
      "refs": [
        "packages/catalog/total.py",
        "tests/test_catalog.py",
        "fixtures/order.json"
      ],
      "sha256": "f384436b658750f4729b9abe96b481932febc5502689ae533da3ffaf5700cdda"
    }
  ]
}

from datetime import date
import json
from pathlib import Path
import shutil
import tempfile
import unittest
from unittest.mock import patch

from tools.check_style import check
from tools.lint_guidance import command_errors, lint, local_path


class GuidanceTests(unittest.TestCase):
    def setUp(self):
        self.temp = tempfile.TemporaryDirectory()
        self.addCleanup(self.temp.cleanup)
        self.root = Path(self.temp.name) / "repo"
        source = Path(__file__).resolve().parents[1]
        shutil.copytree(source, self.root, ignore=shutil.ignore_patterns(
            "__pycache__", ".git", "*.pyc"))
        self.today = date(2026, 10, 5)

    def manifest_change(self, callback):
        path = self.root / "tools/guide_manifest.json"
        data = json.loads(path.read_text())
        callback(data)
        path.write_text(json.dumps(data))

    def test_valid_repository(self):
        self.assertEqual(lint(self.root, self.today), [])

    def test_missing_reference(self):
        (self.root / "docs/ownership.md").unlink()
        self.assertTrue(any("reference is missing" in e
                            for e in lint(self.root, self.today)))

    def test_missing_script(self):
        (self.root / "tools/check_style.py").unlink()
        self.assertTrue(any("script is missing" in e
                            for e in lint(self.root, self.today)))

    def test_missing_module(self):
        (self.root / "packages/catalog/total.py").unlink()
        self.assertTrue(any("module is missing" in e
                            for e in lint(self.root, self.today)))

    def test_missing_tests(self):
        (self.root / "tests/test_catalog.py").unlink()
        self.assertTrue(any("matching tests are missing" in e
                            for e in lint(self.root, self.today)))

    def test_missing_input(self):
        (self.root / "fixtures/order.json").unlink()
        self.assertTrue(any("input is missing" in e
                            for e in lint(self.root, self.today)))

    def test_stale_review(self):
        self.assertTrue(any("review date" in e
                            for e in lint(self.root, date(2027, 2, 1))))

    def test_future_review(self):
        self.assertTrue(any("review date" in e
                            for e in lint(self.root, date(2026, 10, 4))))

    def test_changed_instructions(self):
        path = self.root / "AGENTS.md"
        path.write_text(path.read_text() + "\nNew rule.\n")
        self.assertTrue(any("content changed" in e
                            for e in lint(self.root, self.today)))

    def test_shell_is_not_executed(self):
        command = "python3 tools/check_style.py; touch SENTINEL"
        self.assertTrue(command_errors(self.root, Path("."), command))
        self.assertFalse((self.root / "SENTINEL").exists())

    def test_traversal(self):
        with self.assertRaises(ValueError):
            local_path(self.root, "../outside")

    def test_symlink_escape(self):
        (self.root / "escape").symlink_to(self.root.parent, target_is_directory=True)
        with self.assertRaises(ValueError):
            local_path(self.root, "escape/outside")

    def test_unknown_command(self):
        self.assertTrue(command_errors(self.root, Path("."), "npm test"))

    def test_missing_executable(self):
        with patch("tools.lint_guidance.shutil.which", return_value=None):
            self.assertTrue(command_errors(self.root, Path("."),
                                           "python3 tools/check_style.py"))

    def test_malformed_manifest(self):
        (self.root / "tools/guide_manifest.json").write_text("broken")
        self.assertTrue(any("manifest error" in e
                            for e in lint(self.root, self.today)))

    def test_manifest_wrong_shape(self):
        self.manifest_change(lambda data: data.update(max_age_days=-1))
        self.assertEqual(lint(self.root, self.today), ["invalid manifest shape"])

    def test_manifest_symlink_escape(self):
        path = self.root / "tools/guide_manifest.json"
        outside = self.root.parent / "outside-manifest.json"
        path.rename(outside)
        path.symlink_to(outside)
        with patch.object(Path, "read_text", side_effect=AssertionError(
                "rejected manifest must not be read")):
            errors = lint(self.root, self.today)
        self.assertTrue(any("outside repository" in e for e in errors))

    def test_manifest_parent_symlink_escape(self):
        path = self.root / "tools"
        outside = self.root.parent / "outside-tools"
        path.rename(outside)
        path.symlink_to(outside, target_is_directory=True)
        with patch.object(Path, "read_text", side_effect=AssertionError(
                "rejected manifest must not be read")):
            errors = lint(self.root, self.today)
        self.assertTrue(any("outside repository" in e for e in errors))

    def test_manifest_internal_symlink(self):
        path = self.root / "tools/guide_manifest.json"
        target = self.root / "docs/guide_manifest.json"
        path.rename(target)
        path.symlink_to(target)
        self.assertEqual(lint(self.root, self.today), [])

    def test_missing_guide(self):
        (self.root / "AGENTS.md").unlink()
        self.assertTrue(any("guide is missing" in e
                            for e in lint(self.root, self.today)))

    def test_style_checker(self):
        (self.root / "packages/bad.py").write_text("x = 1 \n")
        self.assertTrue(any("style violation" in e for e in check(self.root)))